#### 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:

  - On unix systems, `/bin/sh` is used.
  - On Windows systems, the value of the environment variable `COMSPEC` is used. If that is not set, `cmd.exe` is used for Windows NT, or `command.com` is used for Windows 9x; in each case the shell is found by searching the path.

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