Previous: Querying the process environment, Up: Support For Unix
External programs can be run with sb-ext:run-program.
1
run-programcreates a new process specified by theprogramargument.argsare 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-programwill return aprocessstructure. See thecmuCommon Lisp Users Manual for details about theprocessstructure.Notes about Unix environments (as in the
:environmentand:envargs):The
- The
sbclimplementation ofrun-program, like Perl and many other programs, but unlike the originalcmuclimplementation, 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.)
&keyarguments 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
cmucl:search- Look for
programin 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-ptyslot 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-inputslot is filled in with a stream that sends its output to the process. Defaults tonil.:if-input-does-not-exist(when:inputis the name of a file)- can be one of:
:errorto generate an error:createto create an empty filenil(the default) to returnnilfromrun-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-outputslot is filled in with a stream that can be read to get the output. Defaults tonil.:if-output-exists(when:outputis the name of a file)- can be one of:
:error(the default) to generate an error:supersedeto supersede the file with output from the program:appendto append output from the program to the filenilto returnnilfromrun-program, without doing anything:errorand:if-error-exists- Same as
:outputand:if-output-exists, except that:errorcan also be specified as:outputin 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
processto quit running for some reason. Whencheck-for-stoppedist, also returns whenprocessis 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
processand stop maintaining the status slot.
Hand
signaltoprocess. Ifwhomis:pid, use the kill Unix system call. Ifwhomis:process-group, use the killpg Unix system call. Ifwhomis:pty-process-groupdeliver 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.