Description

Subprocess Object

Author

Kon Lovett

Requires

Usage

(require-extension osprocess)

Download

osprocess.egg

Documentation

All query routines will return (void) when the query result is meaningless. Example: the exit-code for a process that hasn't started.

A "reaper" task is provided to automatically wait on processes so "zombies" are not created from unattended asynchronous processes.

Constructors

procedure: (make-osprocess COMMAND [#:shell? #f] [#:pseudo-tty? #f] [#:reap? #t] [#:fork? #t] [#:wait? #f] [#:exact? #f] [#:search? #f] [#:collect? #f] [#:abnormal-exit-error? #f] [#:signal-mask #f] [#:current-user-id #f] [#:effective-user-id #f] [#:current-group-id #f] [#:effective-group-id #f] [#:output #t] [#:input #t] [#:error #t] [#:output-buffer #f] [#:input-buffer #f] [#:error-buffer #f] [#:output-mode #f] [#:input-mode #f] [#:error-mode #f] [#:arguments #f] [#:environment #f] [ARGUMENT ...])

Returns an osprocess object.

COMMAND The name of the process executable.
ARGUMENT A command-line argument, an object (which will be converted to a string). All arguments and any keyword arguments are combined.
shell?: Run the process under the system shell? Will construct a command-line from any arguments.
pseudo-tty?: Run the process with a pseudo-terminal? Either #t or a list of pty name, window width & height.
reap?: Automatically wait for the process to exit?
fork?: Create child process? When #f the current process is replaced.
wait?: Immediately wait for the process to exit? Overrides reaping. Synchronous subprocess.
exact?: Treat arguments as given when #t. Otherwise argument quoting is performed when constructing a shell command-line.
search?: Search for the COMMAND pathname when no directory component? A boolean, directory path or list of directory paths. When #t searches using the PATH environment variable, otherwise searches the supplied directory path(s).
collect?: Automatically collect the stream from input ports? A boolean, procedure or list of boolean or procedure. When a list first element is the input port collector and the seconds is the error port collector. A boolean #f means no collection, #t means use default collector. A procedure must take a single input-port parameter and return some object. The default collector procedure is 'read-all'.
abnormal-exit-error?: Is an abnormal exit an error? Will raise a process-exception upon abnormal termination.
signal-mask: List of signals. The signal-mask for the child process.
current-user-id: The current user id for the child process.
effective-user-id: The current effective user id for the child process.
current-group-id: The current group id for the child process.
effective-group-id: The current effective group id for the child process.
output: An output-port for the child process stdout, a pathname, a fileno for redirection, #t for pipe, or #f for shared.
input: An input-port for the child process stdin, a pathname, a fileno for redirection, #t for pipe, or #f for shared.
error: An output-port for the child process stderr, a pathname, a fileno for redirection, #t for pipe, or #f for shared.
output-buffer: A buffer size, or a supplied buffer, for the created parent output-port.
input-buffer: A buffer size, or a supplied buffer, for the created parent input-port.
error-buffer: A buffer size, or a supplied buffer, for the created parent error-port.
output-mode: Open mode flags or a list - (<open mode flags> [<creation permission flags>]).
input-mode: Open mode flags or a list - (<open mode flags> [<creation permission flags>]).
error-mode: Open mode flags or a list - (<open mode flags> [<creation permission flags>]).
arguments: A list of objects (which will be converted to strings).
environment: A list of strings ("ENVVAR=ENVVAL"), or a list of name-value pairs (which will be converted to strings).

When #:shell? is #t the COMMAND may be the command-line. In which case the #:arguments must be not be supplied. Should #:arguments be provided the command-line is built from the COMMAND and the #:arguments, quoting if necessary. Any ARGUMENT parameters are always passed on as trailing arguments to the shell.

The #:signal-mask, #:output-mode, #:input-mode, and #:error-mode option values require the posix unit.

The #:output-mode, #:input-mode, and #:error-mode have default open modes of open/wronly, open/rdonly, and open/wronly, respectively. Any other required open mode flags must be supplied.

The use of #:pseudo-tty? will ignore the #:shell?, #:fork?, and #:input, #:output, #:error with supplied port.

Input stream collection/draining is performed automatically when a "hanging" process wait is invoked. This is done immediately for a synchronous process. Otherwise the programmer must invoke an osprocess-empty-* procedure or wait explicitly for an asynchronous process.

On Windows the #:signal-mask, #:pseudo-tty?, #:fork?, #:input-buffer, #:output-buffer, #:error-buffer, #:input-mode, #:output-mode, #:error-mode, #:input, #:output, #:error are ignored. The #:exact? parameter will also inhibit argument quoting in all cases, not just command-line construction.

procedure: (osprocess COMMAND [#:shell? #f] [#:pseudo-tty? #f] [#:reap? #t] [#:fork? #t] [#:wait? #f] [#:exact? #f] [#:search? #f] [#:collect? #f] [#:abnormal-exit-error? #f] [#:signal-mask #f] [#:output #t] [#:input #t] [#:error #t] [#:output-buffer #f] [#:input-buffer #f] [#:error-buffer #f] [#:output-mode #f] [#:input-mode #f] [#:error-mode #f] [#:arguments #f] [#:environment #f] [ARGUMENT ...])

Like make-osprocess but starts the process. Returns (values pid input-port output-port error-port osprocess-object).

Unlike make-osprocess when no arguments are supplied a shell is automatically used, unless #:shell? is #f.

Predicates & Queries

procedure: (osprocess-list)

Returns a list of all the active osprocesses. Once an osprocess has exited it is removed from the list.

procedure: (osprocess? OBJECT)

Is the OBJECT an osprocess?

procedure: (osprocess-pseudo-tty? OSPROCESS)

Returns either #f when not a pseudo-tty, or a list - (<slave-name> <window-width> <window-height>).

procedure: (osprocess-shell? OSPROCESS)

Is a shell used to run the process?

procedure: (osprocess-forked? OSPROCESS)

Is the subprocess to be forked?

procedure: (osprocess-waited? OSPROCESS)

Is the subprocess to be synchronous?

procedure: (osprocess-started? OSPROCESS)

Has the process started?

procedure: (osprocess-running? OSPROCESS)

Is the process alive?

procedure: (osprocess-alive? OSPROCESS)

Is the process alive?

procedure: (osprocess-exited? OSPROCESS)

Has the process exited?

procedure: (osprocess-command OSPROCESS)

Returns the process command pathname or command-line, depending on whether a shell used to run the process.

procedure: (osprocess-arguments OSPROCESS)

Returns the process arguments or #f. This can be #f even when arguments were supplied due to the use of a shell to run the process.

procedure: (osprocess-environment OSPROCESS)

Returns the process environment or #f.

procedure: (osprocess-pid OSPROCESS)

Returns the system identifier for this process.

procedure: (osprocess-start-seconds OSPROCESS)

When was the process started (approximate).

procedure: (osprocess-exit-seconds OSPROCESS)

When did the process exit (very approximate).

procedure: (osprocess-exit-normal? OSPROCESS)

Did the process exit normally?

procedure: (osprocess-exit-code OSPROCESS)

Returns the process exit status or signal.

procedure: (osprocess-exit-status OSPROCESS)

Returns the process exit status or #f when abnormal exit.

procedure: (osprocess-exit-signal OSPROCESS)

Returns the process exit signal or #f when normal exit.

procedure: (osprocess-input-port OSPROCESS)

Returns the stdin input port or #f when a port specification was supplied.

procedure: (osprocess-output-port OSPROCESS)

Returns the stdout output port or #f when a port specification was supplied.

procedure: (osprocess-error-port OSPROCESS)

Returns the stderr input port or #f when a port specification was supplied.

procedure: (osprocess-ports OSPROCESS)

Returns (values input-port output-port error-port).

procedure: (osprocess-connection OSPROCESS)

Returns (values pid input-port output-port error-port).

procedure: (osprocess-input-port-collection OSPROCESS)

The collected output object for the input-port.

procedure: (osprocess-error-port-collection OSPROCESS)

The collected output object for the error-port.

procedure: (osprocess-error OSPROCESS)

Returns the last captured exception and resets to #f.

Queries & Modifiers

procedure: (osprocess-priority OSPROCESS [PRIORITY])

Gets or sets the process priority. PRIORITY must be an integer [-20 20] to set the priority.

Note that only the superuser can lower a priority.

procedure: (osprocess-collect-input-port OSPROCESS [COLLECTOR])

Gets or sets the automatic collection operation for the input-port output stream using the specified COLLECTOR. When COLLECTOR is #f collecting is disabled, when #t the default is used. Otherwise the COLLECTOR must be a procedure of one argument, an input-port, and returning some object, usually a string.

procedure: (osprocess-collect-error-port OSPROCESS [COLLECTOR])

Like osprocess-collect-input-port but for the error-port.

procedure: (osprocess-collect-ports OSPROCESS [COLLECTOR])

Like osprocess-collect-input-port but for the input-port & error-port.

Actions

procedure: (osprocess-empty-input-port OSPROCESS)

Drains or collects the input port of a started OSPROCESS.

procedure: (osprocess-empty-error-port OSPROCESS)

Drains or collects the error port of a started OSPROCESS.

procedure: (osprocess-empty-ports OSPROCESS)

Drains or collects the input & error ports of a started OSPROCESS.

procedure: (osprocess-close-input-port OSPROCESS)

Closes a created input-port.

procedure: (osprocess-close-output-port OSPROCESS)

Closes a created output-port.

procedure: (osprocess-close-error-port OSPROCESS)

Closes a created error-port.

procedure: (osprocess-close-ports OSPROCESS)

Closes all created ports.

procedure: (osprocess-run OSPROCESS)

Starts the osprocess and returns (values pid input-port output-port error-port).

procedure: (osprocess-wait OSPROCESS [NOHANG #f])

Waits, or not, depending on NOHANG, for the osprocess to exit. Returns (values pid exit-normal? exit-code), where pid is 0 when the osprocess has not exited.

procedure: (osprocess-wait-any [NOHANG #f])

Waits for any osprocess to exit. Returns the osprocess that exited or #f when an osprocess has not exited.

Currently this waits on any child process, not just osprocesses!

procedure: (osprocess-kill OSPROCESS [FORCE? #f])

On UNIX systems sends signal/term to the process, unless FORCE? is #t in which case signal/kill is sent.

procedure: (osprocess-stop OSPROCESS)

On UNIX systems sends signal/stop to the osprocess.

procedure: (osprocess-continue OSPROCESS)

On UNIX systems sends signal/cont to the osprocess.

procedure: (osprocess-signal OSPROCESS SIGNAL)

On UNIX systems sends SIGNAL to the osprocess.

Reaper Procedures

parameter: (osprocess-reaper-period [SECONDS 10.0])

How many seconds between checking for zombies. Will take effect when the reaper resets or starts.

procedure: (osprocess-reap OSPROCESS [FLAG])

Gets or sets the reaping operation.

procedure: (osprocess:remove-sigchld-handler)

Removes the SIGCHLD handler. Do not call this unless absolutely necessary.

Issues

Do not modify the definition values; copies are neither kept nor returned!

Use of a shell will cause the osprocess-command and osprocess-arguments queries to reflect the execution values, not the definition values.

Incomplete Windows support.

Version

License

Copyright (c) 2006, Kon Lovett.  All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the Software),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.