call-system-showing-output

call-system-showing-output Function

Summary

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

Package

system

Signature

call-system-showing-output command &key current-directory prefix show-cmd output-stream wait shell-type kill-process-on-abort external-format => status, output-string-or-signal-number

Arguments

`command`⇩	A string, a non-empty list of strings, a simple-vector of strings, or `nil`.
`current-directory`⇩	`nil` or a pathname designator.
`prefix`⇩	A string.
`show-cmd`⇩	A boolean.
`output-stream`⇩	An output stream or `nil`, `t` or `:tty`.
`wait`⇩	A boolean.
`shell-type`⇩	A string. Supported only on non-Windows platforms.
`kill-process-on-abort`⇩
	A generalized boolean.
`external-format`⇩	An external file format designator. Defaults to `:default`. New in LispWorks 8.1.

Values

`status`	The exit status of the invoked shell or process.
`output-string-or-signal-number`⇩
	A string, an integer or `nil`.

Description

The function call-system-showing-output is an extension to call-system which allows output to be redirected. On non-Windows platforms this means it can be redirected to places other than the shell process from which the LispWorks image was invoked. call-system-showing-output therefore allows the user to, for example, invoke a shell command and redirect the output to the current Listener window.

command is interpreted as by call-system. On Microsoft Windows there is one difference: when command is a non-empty list or vector and the executable (that is, the first element of the sequence command) in call-system-showing-output is not a GUI application, LispWorks hides the first window, which is the console that the executable will normally open. Note that for a non-direct command (that is, a string) LispWorks always hides the first window (which is the console) in both call-system and call-system-showing-output.

If current-directory is non-nil, then it must be a pathname designator for a directory and is used as the current directory in the new process. Otherwise, the current directory of the LispWorks process is used (the default).

prefix is a prefix to be printed at the start of any output line. The default value is "; ".

show-cmd specifies whether or not the cmd invoked will be printed as well as the output for that command. If t then cmd will be printed. The default value for show-cmd is t.

output-stream specifies where the output will be sent to. If output-stream is an output stream, the output is written to it. If output-stream is t, the output is written to *standard-output*. If output-stream is nil, the output is collected as a string, and returned as a second value output-string-or-signal-number. If output-stream is :tty, call-system-showing-output behaves like call-system. The default value is *standard-output*. On non-Windows platforms, if output-stream is non-nil and the process was terminated by a signal, then the second return value output-string-or-signal-number is the number of that signal. For a discussion of these return values see 27.7.1 Interpreting the exit status.

If wait is true, call-system-showing-output does not return until the process has exited. If nil, call-system-showing-output returns immediately and no output is shown. The default for wait is t.

shell-type is a string naming a UNIX shell. The default is "/bin/sh".

If kill-process-on-abort is true, then when call-system-showing-output is aborted the process is killed. The default value of kill-process-on-abort is nil.

external-format specifies the external format to use if it is not :default. See 26.7 External Formats to translate Lisp characters from/to external encodings for a description of external formats. external-format is ignored if wait is nil or output-stream is :tty.

On non-Windows platforms, if external-format is :default, then LispWorks tries to determine the external format to use using the POSIX environment variables LC_ALL, LC_CTYPE and LANG (in that order). If it fails to find a known external format, call-system-showing-output creates a stream that does not use an external format.

On Windows if external-format is :default it does not use external format.

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.

call-system-showing-output returns the exit status of the shell invoked to execute the command on non-Windows platforms, or the process created on Microsoft Windows.

Compatibility note

On Microsoft Windows, LispWorks 8.1 and later, current-directory defaults to the current directory of the LispWorks process. In previous releases, it defaulted to the pathname-location of the current-pathname. In practice, this is only different when loading or compiling a file.

Examples

On Linux:

CL-USER 1 > (sys:call-system-showing-output "pwd" :prefix "***")
***pwd
***/amd/xanfs1-cam/u/ldisk/sp/lispsrc/v42/builds
0
 
CL-USER 2 > (sys:call-system-showing-output "pwd" :prefix "&&&"
                                                  :show-cmd nil)
&&&/amd/xanfs1-cam/u/ldisk/sp/lispsrc/v42/builds
0

On Microsoft Windows:

CL-USER 223 > (sys:call-system-showing-output
                        "cmd /c type hello.txt"
                        :prefix "***")
***cmd /c type hello.txt
***Hi there
0
 
CL-USER 224 > (sys:call-system-showing-output
                        "cmd /c type hello.txt"
                        :prefix "&&&"
                        :show-cmd nil)
&&&Hi there
0