14.4 Processes
| ||||||||||||||||||||||||||||||||||||||||||||||
stdout : (or/c output-port? false/c) | ||||||||||||||||||||||||||||||||||||||||||||||
stdin : (or/c input-port? false/c) | ||||||||||||||||||||||||||||||||||||||||||||||
stderr : (or/c output-port? false/c) | ||||||||||||||||||||||||||||||||||||||||||||||
command : path-string? | ||||||||||||||||||||||||||||||||||||||||||||||
arg : string? | ||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||
stdout : (or/c output-port? false/c) | ||||||||||||||||||||||||||||||||||||||||||||||
stdin : (or/c input-port? false/c) | ||||||||||||||||||||||||||||||||||||||||||||||
stderr : (or/c output-port? false/c) | ||||||||||||||||||||||||||||||||||||||||||||||
command : path-string? | ||||||||||||||||||||||||||||||||||||||||||||||
exact : (one-of/c 'exact) | ||||||||||||||||||||||||||||||||||||||||||||||
arg : string? |
Creates a new process in the underlying operating system to execute command asynchronously. See also system and process from scheme/system.
The command argument is a path to a program executable, and the args are command-line arguments for the program. Under Unix and Mac OS X, command-line arguments are passed as byte strings using the current locale’s encoding (see Encodings and Locales).
Under Windows, the first arg can be replaced with 'exact, which triggers a Windows-specific behavior: the sole arg is used exactly as the command-line for the subprocess. Otherwise, under Windows, a command-line string is constructed from command and arg so that a typical Windows console application can parse it back to an array of arguments. If 'exact is provided on a non-Windows platform, the exn:fail:contract exception is raised.
For information on the Windows command-line conventions, search for “command line parsing” at http://msdn.microsoft.com/.
Unless it is #f, stdout is used for the launched process’s standard output, stdin is used for the process’s standard input, and stderr is used for the process’s standard error. All provided ports must be file-stream ports. Any of the ports can be #f, in which case a system pipe is created and returned by subprocess. For each port that is provided, no pipe is created and the corresponding returned value is #f.
The subprocess procedure returns four values:
a subprocess value representing the created process;
an input port piped from the process’s standard output, or #f if stdout-output-port was a port;
an output port piped to the process standard input, or #f if stdin-input-port was a port;
an input port piped from the process’s standard error, or #f if stderr-output-port was a port.
Important: All ports returned from subprocess must be explicitly closed with close-input-port or close-output-port.
The returned ports are file-stream ports (see File Ports), and they are placed into the management of the current custodian (see Custodians). The exn:fail exception is raised when a low-level error prevents the spawning of a process or the creation of operating system pipes for process communication.
(subprocess-wait subproc) → void? |
subproc : subprocess? |
Blocks until the process represented by subproc terminates.
| |||||||
subproc : subprocess? |
Returns 'running if the process represented by subproc is still running, or its exit code otherwise. The exit code is an exact integer, and 0 typically indicates success. If the process terminated due to a fault or signal, the exit code is non-zero.
(subprocess-kill subproc force?) → void? |
subproc : subprocess? |
force? : any/c |
Terminates the subprocess represented by subproc if force? is true and if the process still running. If an error occurs during termination, the exn:fail exception is raised.
If force? is #f under Unix and Mac OS X, the subprocess is sent an interrupt signal instead of a kill signal (and the subprocess might handle the signal without terminating). Under Windows, no action is taken when force? is #f.
(subprocess-pid subproce) → nonnegative-exact-integer? |
subproce : subprocess? |
Returns the operating system’s numerical ID (if any) for the process represented by subproc, valid only as long as the process is running.
(subprocess? v) → boolean? |
v : any/c |
Returns #t if v is a subprocess value, #f otherwise.
| |||||||||||||||||||||||||||||||||||
target : string? | |||||||||||||||||||||||||||||||||||
parameters : string? | |||||||||||||||||||||||||||||||||||
dir : path-string? | |||||||||||||||||||||||||||||||||||
show-mode : symbol? |
Performs the action specified by verb on target in Windows. For platforms other than Windows, the exn:fail:unsupported exception is raised.
For example,
(shell-execute #f "http://www.plt-scheme.org" "" |
(current-directory) 'sw_shownormal) |
Opens the PLT Scheme home page in a browser window.
The verb can be #f, in which case the operating system will use a default verb. Common verbs include "open", "edit", "find", "explore", and "print".
The target is the target for the action, usually a filename path. The file could be executable, or it could be a file with a recognized extension that can be handled by an installed application.
The parameters argument is passed on to the system to perform the action. For example, in the case of opening an executable, the parameters is used as the command line (after the executable name).
The dir is used as the current directory when performing the action.
The show-mode sets the display mode for a Window affected by the action. It must be one of the following symbols; the description of each symbol’s meaning is taken from the Windows API documentation.
'sw_hide or 'SW_HIDE – Hides the window and activates another window.
'sw_minimize or 'SW_MINIMIZE – Minimizes the window and activates the next top-level window in the z-order.
'sw_restore or 'SW_RESTORE – Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position.
'sw_show or 'SW_SHOW – Activates the window and displays it in its current size and position.
'sw_showmaximized or 'SW_SHOWMAXIMIZED – Activates the window and displays it as a maximized window.
'sw_showminimized or 'SW_SHOWMINIMIZED – Activates the window and displays it as a minimized window.
'sw_showminnoactive or 'SW_SHOWMINNOACTIVE – Displays the window as a minimized window. The active window remains active.
'sw_showna or 'SW_SHOWNA – Displays the window in its current state. The active window remains active.
'sw_shownoactivate or 'SW_SHOWNOACTIVATE – Displays a window in its most recent size and position. The active window remains active.
'sw_shownormal or 'SW_SHOWNORMAL – Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position.
If the action fails, the exn:fail exception is raised. If the action succeeds, the result is #f.
In future versions of Scheme, the result may be a subprocess value if the operating system did returns a process handle (but if a subprocess value is returned, its process ID will be 0 instead of the real process ID).
14.4.1 Simple Subprocesses
The bindings documented in this section are provided by the scheme/system library, not scheme/base or scheme.
command : string? |
Executes a Unix, Mac OS X, or Windows shell command synchronously (i.e., the call to system does not return until the subprocess has ended). The command argument is a string containing no nul characters. If the command succeeds, the return value is #t, #f otherwise.
command : path-string? |
arg : string? |
command : path-string? |
exact : (one-of/c 'exact) |
arg : string? |
Like system, except that command is a filename that is executed directly (instead of through a shell command), and the args are the arguments. The executed file is passed the specified string arguments (which must contain no nul characters).
Under Windows, the first argument after command can be 'exact, and the final arg is a complete command line. See subprocess for details.
(system/exit-code command) → (integer-in 0 255) |
command : string? |
Like system, except that the result is the exit code returned by the subprocess. A 0 result normally indicates success.
(system*/exit-code command arg ) → (integer-in 0 255) |
command : path-string? |
arg : string? |
(system*/exit-code command exact arg) → (integer-in 0 255) |
command : path-string? |
exact : (one-of/c 'exact) |
arg : string? |
Like system*, but returns the exit code like system/exit-code.
(process command) | |||||||||
| |||||||||
command : string? |
Executes a shell command asynchronously. The result is a list of five values:
an input port piped from the subprocess’s standard output,
an output port piped to the subprocess standard input,
the system process id of the subprocess,
an input port piped from the subprocess’s standard error, and
a procedure of one argument, either 'status, 'wait, 'interrupt, or 'kill:
'status returns the status of the subprocess as one of 'running, 'done-ok, or 'done-error.
'exit-code returns the integer exit code of the subprocess or #f if it is still running.
'wait blocks execution in the current thread until the subprocess has completed.
'interrupt sends the subprocess an interrupt signal under Unix and Mac OS X, and takes no action under Windows. The result is #<void>.
'kill terminates the subprocess and returns #<void>.
Important: All three ports returned from process must be explicitly closed with close-input-port or close-output-port.
command : path-string? |
arg : string? |
command : path-string? |
exact : (one-of/c 'exact) |
arg : string? |
Like process, except that command is a filename that is executed directly, and the args are the arguments. Under Windows, as for system*, the first arg can be replaced with 'exact.
(process/ports out in error-out command) → list? |
out : (or/c false/c output-port?) |
in : (or/c false/c input-port?) |
error-out : (or/c false/c output-port?) |
command : string? |
Like process, except that out is used for the process’s standard output, in is used for the process’s standard input, and error-out is used for the process’s standard error. Any of the ports can be #f, in which case a system pipe is created and returned, as in process. For each port that is provided, no pipe is created, and the corresponding value in the returned list is #f.
| ||||||||||||||||||||||||||||||||||||||||||
out : (or/c false/c output-port?) | ||||||||||||||||||||||||||||||||||||||||||
in : (or/c false/c input-port?) | ||||||||||||||||||||||||||||||||||||||||||
error-out : (or/c false/c output-port?) | ||||||||||||||||||||||||||||||||||||||||||
command : path-string? | ||||||||||||||||||||||||||||||||||||||||||
arg : string? | ||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||
out : (or/c false/c output-port?) | ||||||||||||||||||||||||||||||||||||||||||
in : (or/c false/c input-port?) | ||||||||||||||||||||||||||||||||||||||||||
error-out : (or/c false/c output-port?) | ||||||||||||||||||||||||||||||||||||||||||
command : path-string? | ||||||||||||||||||||||||||||||||||||||||||
exact : (one-of/c 'exact) | ||||||||||||||||||||||||||||||||||||||||||
arg : string? |
Like process*, but with the port handling of process/ports.