Previous: Subprocess Conditions, Up: Subprocesses


15.7.3 Subprocess Options

The following subprocess options may be passed to run-shell-command or run-synchronous-subprocess. These options are passed as alternating keyword/value pairs, for example:

     (run-shell-command "ls /"
                        'output my-output-port
                        'output-buffer-size 8192)

The example shows a shell command being run with two options specified: output and output-buffer-size.

— subprocess option: input port

Specifies the standard input of the subprocess. Port may be an input port, in which case characters are read from port and fed to the subprocess until port reaches end-of-file. Alternatively, port may be #f, indicating that the subprocess has no standard input.

The default value of this option is #f.

          (call-with-input-file "foo.in"
            (lambda (port)
              (run-shell-command "cat > /dev/null" 'input port)))
     
— subprocess option: input-line-translation line-ending

Specifies how line-endings should be translated when writing characters to the subprocess. Ignored if the input option is #f. Line-ending must be either a string specifying the line ending, or the symbol default, meaning to use the operating system's standard line ending. In either case, newline characters to be written to the input port are translated to the specified line ending before being written.

The default value of this option is default.

          (call-with-input-file "foo.in"
            (lambda (port)
              (run-shell-command "cat > /dev/null"
                                 'input port
                                 'input-line-translation "\r\n")))
     
— subprocess option: input-buffer-size n

Specifies the size of the input buffer for the standard input of the subprocess. (This is the buffer on the Scheme side, and has nothing to do with any buffering done on the subprocess side.) Ignored if the input option is #f. N must be an exact positive integer specifying the number of characters the buffer can hold.

The default value of this option is 512.

          (call-with-input-file "foo.in"
            (lambda (port)
              (run-shell-command "cat > /dev/null"
                                 'input port
                                 'input-buffer-size 4096)))
     
— subprocess option: output port

Specifies the standard output and standard error of the subprocess. Port may be an output port, in which case characters are read from the subprocess and fed to port until the subprocess finishes. Alternatively, port may be #f, indicating that the subprocess has no standard output or standard error.

The default value of this option is the value of (current-output-port).

          (call-with-output-file "foo.out"
            (lambda (port)
              (run-shell-command "ls -la /etc" 'output port)))
     
— subprocess option: output-line-translation line-ending

Specifies how line-endings should be translated when reading characters from the standard output of the subprocess. Ignored if the output option is #f. Line-ending must be either a string specifying the line ending, or the symbol default, meaning to use the operating system's standard line ending. In either case, newline characters read from the subprocess port are translated to the specified line ending.

The default value of this option is default.

          (call-with-output-file "foo.out"
            (lambda (port)
              (run-shell-command "ls -la /etc"
                                 'output port
                                 'output-line-translation "\r\n")))
     
— subprocess option: output-buffer-size n

Specifies the size of the output buffer for the standard output of the subprocess. (This is the buffer on the Scheme side, and has nothing to do with any buffering done on the subprocess side.) Ignored if the output option is #f. N must be an exact positive integer specifying the number of characters the buffer can hold.

The default value of this option is 512.

          (call-with-output-file "foo.out"
            (lambda (port)
              (run-shell-command "ls -la /etc"
                                 'output port
                                 'output-buffer-size 4096)))
     
— subprocess option: redisplay-hook thunk

Specifies that thunk is to be run periodically when output from the subprocess is available. Thunk must be a procedure of no arguments, or #f indicating that no hook is supplied. This option is mostly useful for interactive systems. For example, the Edwin text editor uses this to update output buffers when running some subprocesses.

The default value of this option is #f.

          (run-shell-command "ls -la /etc"
                             'redisplay-hook
                             (lambda ()
                               (update-buffer-contents buffer)))
     
— subprocess option: environment environment

Specifies the environment variables that are to be used for the subprocess. Environment must be either a vector of strings or #f indicating the default environment. If it is a vector of strings, each string must be a name/value pair where the name and value are separated by an equal sign, for example, "foo=bar". To define a variable with no value, just omit the value, as in "foo=".

Note that the variable scheme-subprocess-environment is bound to the default subprocess environment.

The default value of this option is #f.

          (run-shell-command "ls -la /etc"
                             'environment
                             (let* ((v scheme-subprocess-environment)
                                    (n (vector-length v))
                                    (v (vector-grow v (+ n 1))))
                               (vector-set! v n "TERM=none")
                               v))
     
— subprocess option: working-directory pathname

Specifies the working directory in which the subprocess will run.

The default value of this option is (working-directory-pathname).

          (run-shell-command "ls -la" 'working-directory "/etc/")
     
— subprocess option: use-pty? boolean

This option is meaningful only on unix systems; on other systems it is ignored. Specifies whether to communicate with the subprocess using pty devices; if true, ptys will be used, otherwise pipes will be used.

The default value of this option is #f.

          (run-shell-command "ls -la /etc" 'use-pty? #t)
     
— subprocess option: shell-file-name pathname

Specifies the shell program to use for run-shell-command.

The default value of this option is (os/shell-file-name). This is the value of the environment variable SHELL, or if SHELL is not set, the value is operating-system dependent as follows:

          (run-shell-command "ls -la /etc"
                             'shell-file-name "/usr/local/bin/bash")