s48-refman/posix/process.texi

@node POSIX processes
@section Processes

@stindex posix-processes
The procedures described in this section control the creation of
subprocesses and the execution of programs.  They exported by both the
@code{posix-processes} and @code{posix} structures.

@cindex forking
@cindex process forking
@cindex POSIX @code{fork}
@deffn procedure fork @returns{} process id or @code{#f}
@deffnx procedure fork-and-forget thunk @returns{} unspecified
@code{Fork} creates a new child process.  In the parent process, it
returns the child's process id; in the child process, it returns
@code{#f}.  @code{Fork-and-forget} calls @var{thunk} in a new process;
no process id is returned.  @code{Fork-and-forget} uses an intermediate
process to avoid creating a zombie.
@end deffn

@cindex process ids
@cindex POSIX process ids
@deffn procedure process-id? object @returns{} boolean
@deffnx procedure process-id=? pid@suba{a} pid@suba{b} @returns{} boolean
@deffnx procedure process-id->integer pid @returns{} integer
@deffnx procedure integer->process-id integer @returns{} pid
@code{Process-id?} is the disjoint type predicate for process ids.
@code{Process-id=?} tests whether two process ids are the same.
@code{Process-id->integer} & @code{integer->process-id} convert between
Scheme48's opaque process id type and POSIX process id integers.
@end deffn

@cindex process termination
@cindex POSIX process termination
@cindex waiting for POSIX processes
@deffn procedure process-id-exit-status pid @returns{} integer or @code{#f}
@deffnx procedure process-id-terminating-signal pid @returns{} signal or @code{#f}
@deffnx procedure wait-for-child-process pid @returns{} unspecified
If the process identified by @var{pid} exited normally or is running,
@code{process-id-exit-status} and @code{process-id-terminating-signal}
will both return @code{#f}.  If, however, it terminated abnormally,
@code{process-id-exit-status} returns its exit status, and if it exited
due to a signal then @code{process-id-terminating-signal} returns the
signal due to which it exited.  @code{Wait-for-child-process} blocks
the current process until the process identified by @var{pid} has
terminated.  Scheme48 may reap child processes before the user requests
their exit status, but it does not always do so.
@end deffn

@cindex exiting processes
@cindex POSIX process exiting
@deffn procedure exit status @returns{} does not return
Terminates the current process with the integer @var{status} as its
exit status.
@end deffn

@cindex executing processes
@cindex POSIX @code{exec}
@deffn procedure exec program argument @dots{} @returns{} does not return
@deffnx procedure exec-with-environment program env argument @dots{} @returns{} does not return
@deffnx procedure exec-file filename argument @dots{} @returns{} does not return
@deffnx procedure exec-file-with-environment filename env argument @dots{} @returns{} does not return
These all replace the current program with a new one.  They differ in
how the program is found and what process environment the program
should receive.  @code{Exec} & @code{exec-with-environment} look up
the program in the search path (the @code{PATH} environment variable),
while @code{exec-file} & @code{exec-file-with-environment} execute a
particular file.  The environment is either inherited from the
current process, in the cases of @code{exec} & @code{exec-file}, or
explicitly specified, in the cases of @code{exec-with-environment} &
@code{exec-file-with-environment}.  @var{Program}, @var{filename}, &
all @var{argument}s should be strings.  @var{Env} should be a list of
strings of the form @code{"@var{name}=@var{value}"}.  When the new
program is invoked, its arguments consist of the program name prepended
to the remaining specified arguments.
@end deffn

@deffn procedure exec-with-alias name lookup? maybe-env arguments @returns{} does not return
General omnibus procedure that subsumes the other @code{exec} variants.
@var{Name} is looked up in the search path if @var{lookup?} is true or
used as an ordinary filename if it is false.  @var{Maybe-env} is either
@code{#f}, in which case the new program's environment should be
inherited from the current process, or a list of strings of the above
form for environments, which specifies the new program's environment.
@var{Arguments} is a list of @emph{all} of the program's arguments;
@code{exec-with-alias} does @emph{not} prepend @var{name} to that list
(hence @code{-with-alias}).
@end deffn