Previous: Subprocess Conditions, Up: Subprocesses
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
.
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)))
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 symboldefault
, meaning to use the operating system's standard line ending. In either case, newline characters to be written to theinput
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")))
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)))
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)))
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 symboldefault
, 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")))
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)))
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)))
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))
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/")
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)
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 variableSHELL
, or ifSHELL
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")