External programs can be run with sb-ext:run-program
.
1
run-program
creates a new process specified by theprogram
argument.args
are the standard arguments that can be passed to a program. For no arguments, usenil
(which means that just the name of the program is passed as arg 0).The program arguments and the environment are encoded using the default external format for streams.
run-program
will return aprocess
structure. See thecmu
Common Lisp Users Manual for details about theprocess
structure.Notes about Unix environments (as in the
:environment
and:env
args):The
- The
sbcl
implementation ofrun-program
, like Perl and many other programs, but unlike the originalcmu
cl
implementation, copies the Unix environment by default.- Running Unix programs from a setuid process, or in any other situation where the Unix environment is under the control of someone else, is a mother lode of security problems. If you are contemplating doing this, read about it first. (The Perl community has a lot of good documentation about this and other security issues in script-like programs.)
&key
arguments have the following meanings:
:environment
- a list of STRINGs describing the new Unix environment (as in "man environ"). The default is to copy the environment of the current process.
:env
- an alternative lossy representation of the new Unix environment, for compatibility with
cmu
cl
:search
- Look for
program
in each of the directories in the child's $PATH environment variable. Otherwise an absolute pathname is required.:wait
- If non-NIL (default), wait until the created process finishes. If
nil
, continue running Lisp until the program finishes.:pty
- Either
t
,nil
, or a stream. Unlessnil
, the subprocess is established under apty
. If :pty is a stream, all output to this pty is sent to this stream, otherwise theprocess-pty
slot is filled in with a stream connected to pty that can read output and write input.:input
- Either
t
,nil
, a pathname, a stream, or:stream
. Ift
, the standard input for the current process is inherited. Ifnil
, /dev/null is used. If a pathname, the file so specified is used. If a stream, all the input is read from that stream and sent to the subprocess. If:stream
, theprocess-input
slot is filled in with a stream that sends its output to the process. Defaults tonil
.:if-input-does-not-exist
(when:input
is the name of a file)- can be one of:
:error
to generate an error:create
to create an empty filenil
(the default) to returnnil
fromrun-program
:output
- Either
t
,nil
, a pathname, a stream, or:stream
. Ift
, the standard output for the current process is inherited. Ifnil
, /dev/null is used. If a pathname, the file so specified is used. If a stream, all the output from the process is written to this stream. If:stream
, theprocess-output
slot is filled in with a stream that can be read to get the output. Defaults tonil
.:if-output-exists
(when:output
is the name of a file)- can be one of:
:error
(the default) to generate an error:supersede
to supersede the file with output from the program:append
to append output from the program to the filenil
to returnnil
fromrun-program
, without doing anything:error
and:if-error-exists
- Same as
:output
and:if-output-exists
, except that:error
can also be specified as:output
in which case all error output is routed to the same place as normal output.:status-hook
- This is a function the system calls whenever the status of the process changes. The function takes the process as an argument.
When sb-ext:run-program
is called with wait
equal to
NIL, an instance of class sb-ext:process is returned. The
following functions are available for use with processes:
Name of a
queue
. Can be assingned to usingsetf
. Queue names can be arbitrary printable objects, and need not be unique.
Name of a
queue
. Can be assingned to usingsetf
. Queue names can be arbitrary printable objects, and need not be unique.
Name of a
queue
. Can be assingned to usingsetf
. Queue names can be arbitrary printable objects, and need not be unique.
Return the current status of
process
. The result is one of:running
,:stopped
,:exited
, or:signaled
.
Wait for
process
to quit running for some reason. Whencheck-for-stopped
ist
, also returns whenprocess
is stopped. Returnsprocess
.
Name of a
queue
. Can be assingned to usingsetf
. Queue names can be arbitrary printable objects, and need not be unique.
Name of a
queue
. Can be assingned to usingsetf
. Queue names can be arbitrary printable objects, and need not be unique.
Close all streams connected to
process
and stop maintaining the status slot.
Hand
signal
toprocess
. Ifwhom
is:pid
, use the kill Unix system call. Ifwhom
is:process-group
, use the killpg Unix system call. Ifwhom
is:pty-process-group
deliver the signal to whichever process group is currently in the foreground.
[1] In SBCL versions prior to 1.0.13, sb-ext:run-program
searched for executables in a manner somewhat incompatible with other
languages. As of this version, SBCL uses the system library routine
execvp(3)
, and no longer contains the function,
find-executable-in-search-path
, which implemented the old
search. Users who need this function may find it
in run-program.lisp versions 1.67 and earlier in SBCL's CVS
repository here
http://sbcl.cvs.sourceforge.net/sbcl/sbcl/src/code/run-program.lisp?view=log. However,
we caution such users that this search routine finds executables that
system library routines do not.