osprocess
![[Picture of an egg]](egg.jpg)
Subprocess Object
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.
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.
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.
Returns a list of all the active osprocesses. Once an osprocess has exited it is removed from the list.
Is the OBJECT an osprocess?
Returns either #f when not a pseudo-tty, or a list - (<slave-name> <window-width> <window-height>).
Is a shell used to run the process?
Is the subprocess to be forked?
Is the subprocess to be synchronous?
Has the process started?
Is the process alive?
Is the process alive?
Has the process exited?
Returns the process command pathname or command-line, depending on whether a shell used to run the process.
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.
Returns the process environment or #f.
Returns the system identifier for this process.
When was the process started (approximate).
When did the process exit (very approximate).
Did the process exit normally?
Returns the process exit status or signal.
Returns the process exit status or #f when abnormal exit.
Returns the process exit signal or #f when normal exit.
Returns the stdin input port or #f when a port specification was supplied.
Returns the stdout output port or #f when a port specification was supplied.
Returns the stderr input port or #f when a port specification was supplied.
Returns (values input-port output-port error-port).
Returns (values pid input-port output-port error-port).
The collected output object for the input-port.
The collected output object for the error-port.
Returns the last captured exception and resets to #f.
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.
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.
Like osprocess-collect-input-port but for the error-port.
Like osprocess-collect-input-port but for the input-port & error-port.
Drains or collects the input port of a started OSPROCESS.
Drains or collects the error port of a started OSPROCESS.
Drains or collects the input & error ports of a started OSPROCESS.
Closes a created input-port.
Closes a created output-port.
Closes a created error-port.
Closes all created ports.
Starts the osprocess and returns (values pid input-port output-port error-port).
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.
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!
On UNIX systems sends signal/term to the process, unless FORCE? is #t in which case signal/kill is sent.
On UNIX systems sends signal/stop to the osprocess.
On UNIX systems sends signal/cont to the osprocess.
On UNIX systems sends SIGNAL to the osprocess.
How many seconds between checking for zombies. Will take effect when the reaper resets or starts.
Gets or sets the reaping operation.
Removes the SIGCHLD handler. Do not call this unless absolutely necessary.
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.
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.