call-system Function

Summary

Executes a command by a shell or directly by the underlying Operating System.

Package

system

Signature

call-system command &key current-directory wait shell-type => status, signal-number

Arguments

Values

Description

The function call-system allows executables and DOS or Unix shell commands to be called from Lisp code as a separate OS process. The output goes to standard output, as the operating system sees it. (This normally means *terminal-io* in LispWorks.)

If command is a string then it is passed to the shell as the command to run, using the -c option, without any other arguments. The type of shell to run is determined by shell-type as described below. Note that for typical Unix shells, the string command may contain multiple commands separated by ; (semicolon).

If command is a list then it becomes the argv of a command to run directly, without invoking a shell. The first element is the command to run directly and the other elements are passed as arguments on the command line (that is, element 0 has its name in argv[0] in C, and so on).

If command is a simple vector of strings, the element at index 0 is the command to run directly, without invoking a shell. The other elements are the complete set of arguments seen by the command (that is, element 1 becomes argv[0] in C, and so on).

If command is nil, then the shell is run.

On Microsoft Windows, if command is a string, LispWorks hides the first window of the execution of the command, because that is the console that cmd.exe starts in a DOS window. If the command itself is a console application, you may want to see the console. In this case run the command as a direct command. To do this, pass a list or a vector as described above. Conversely, if you run a console application and do not want to see the console, pass the command as a string.

On Microsoft Windows current-directory is the lpCurrentDirectory argument passed to CreateProcess. If this is not supplied, the pathname-location of the current-pathname is passed.

On non-Windows platforms, if shell-type is a string it specifies the shell. If shell-type is nil (the default) then the Bourne shell, /bin/sh, is used. The C shell may be obtained by passing "/bin/csh".

On supported versions of Microsoft Windows if shell-type is nil then cmd.exe is used.

On non-Windows platforms, the command line arguments and environment variables are encoded as specfied in 27.14.1 Encoding of file names and strings in OS interface functions.

If wait is true (the default), then call-system does not return until the process has exited and then returns the exit status status of the process it created. Additionally on non-Windows platforms if the process was terminated by a signal then call-system returns a second value signal-number which is the number of that signal. For a discussion of these return values see 27.7.1 Interpreting the exit status.

If wait is nil, then call-system returns nil as status.

Notes

If you need to be able to check whether the child process is alive and maybe to kill it, use open-pipe with :save-exit-status t (and maybe :direction :none) instead of call-system, and then use pipe-exit-status and maybe pipe-kill-process.

Compatibility notes

1. The argument :shell-type is not implemented in LispWorks for Windows 4.4 and earlier, and cmd.exe is not used implicitly.
2. On Microsoft Windows, LispWorks 5.0 and later use shell-type cmd.exe by default when command is a string. In LispWorks 5.x the user may see a DOS command window in this case, but LispWorks 6.0 and later explicitly hide the DOS window. To call your command directly command should be a list, as in the last example below.

Examples

On Unix-like systems:

(call-system (format nil "tr Z q < ~a > ~a"
                (namestring   a)
                (namestring   b)))

On Microsoft Windows:

(sys:call-system "sleep 3" :wait t)
 
(sys:call-system '("notepad" "myfile.txt"))

See also

open-pipe
call-system-showing-output
run-shell-command
27.7.1 Interpreting the exit status