The fork module contains several low-level functions that may
be used for subprocess creation. Use require("fork") to load it.
Create a new process via the fork system function
Int_Type fork ()
The fork function creates a new child process via the
fork system function. See the approriate documentation for
the actual semantics involved such as what is preserved in the child
process. Upon sucess, the function returns a value that is greater
than 0 to the parent process that represents the child process's id.
It will return 0 to the child process. If the fork function fails, a
value of -1 will be returned and errno set accordingly.
The following example creates a child process to invoke the ``ls''
command on a Unix system. It also illustrates the low-level nature
of the fork and related system calls.
define ls ()
{
variable pid = fork ();
if (pid == -1)
throw OSError, "fork failed: " + errno_string(errno);
if ((pid == 0)
&& (-1 == execvp ("ls", ["ls", "-l"])))
{
() = fprintf (stderr, "execvp failed: " + errno_string(errno));
_exit (1);
}
forever
{
variable status = waitpid (pid, 0);
if (status == NULL)
{
if (errno == EINTR) continue;
throw OSError, "waitpid failed: " + errno_string(errno);
}
return status.exit_status;
}
}
waitpid, execv, execvp, execve, _exit, system
Execute a new process
Int_Type execv(path, argv[])
The execv function may be used to overlay the current process
with a new process by invoking to the program specified by the
path argument. If for some reason the function fails a
value of -1 will be returned with errno set accordingly.
Normally the function will not return.
The argv parameter is an array of strings that will
be used to construct the argument list for the program. For
example, if the invoked program is a C program, the argv
parameter will be correspond to the C program's argv-list.
The path parameter must specify the exact location of the
executable. The related execvp function may be used to
search for the executable along a path.
This function is a wrapper around the corresponding system library function. See the system-specific documentation for more information.
execvp, execve, system, fork, _exit
Execute a new process
Int_Type execve(path, argv[], envp[])
The execve function may be used to overlay the current process
with a new process by invoking to the program specified by the
path argument. If for some reason the function fails a
value of -1 will be returned with errno set accordingly.
Normally the function will not return.
The argv parameter is an array of strings that will
be used to construct the argument list for the program. For
example, if the invoked program is a C program, the argv
parameter will be correspond to the C program's argv-list.
The envp parameter is an array of strings that are used to
initialize the environment of the overlayed program.
This function is a wrapper around the corresponding system library function. See the system-specific documentation for more information.
execv, execvp, system, fork, _exit
Execute a new process
Int_Type execvp(pgm, argv[])
The execvp function may be used to overlay the current process
with a new process by invoking to the program specified by the
pgm argument. If for some reason the function fails a
value of -1 will be returned with errno set accordingly.
Normally the function will not return.
If the pgm argument does specify the directory containing the
program, then a search will be performed for the program using,
e.g., the PATH environment variable.
The argv parameter is an array of strings that will
be used to construct the argument list for the program. For
example, if the invoked program is a C program, the argv
parameter will be correspond to the C program's argv-list.
This function is a wrapper around the corresponding system library function. See the system-specific documentation for more information.
execv, execve, system, fork, _exit
Exit the current processes
_exit(Int_Type status)
Like the related exit function, _exit may be used to
terminate the current process. One of the differences between the two
functions is that the _exit will not invoke various ``atexit''
handlers that are normally run when a program is terminated. See
the system-specific C runtime library documentation for more
information about this function.
The main use of the _exit function is after the failure of
one of the execv functions in a child process.
fork, execv, execvp, execve, waitpid, exit
Wait for a specified process
Struct_Type waitpid (pid, options)
The waitpid function will cause the calling process to wait
for the child process whose process id is pid to change its
state, e.g., exit. It returns information about the process in the
form of a structure with the following fields:
pid The process-id of the child process, 0 if the process
has not changed state.
exited Non-zero if the child exited normally.
exit_status The exit status of the child. This field is
meaninful only if the exited field is non-zero.
signal Non-zero of the child was terminated by a signal.
The value of this field is that of the signal.
coredump Non-zero if the child produced a core-dump as the
result of termination by a signal.
stopped Non-zero if the child was stopped via a signal. The
value is that of the signal that stopped it.
continued Non-zero if the process was continued.
Upon error, the function will return NULL and set errno
accordingly.
The value of the options parameter is the bitwise-or of one
of the following values:
WNOHANG causes waitpid to return immediately if the child has
not terminated. In this case, the value of the pid
field will be 0 if the child is still running.
WUNTRACED (see semantics in the OS documentation)
WCONTINUED (see semantics in the OS documentation)
s = waitpid (pid, WNOHANG);
if (s == NULL)
throw OSError, "waitpid failed: " + errno_string ();
if (s.pid == 0)
message ("The child is still running");
else if (s.exited)
vmessage ("child exited with status %d", s.exit_status);
else if (s.signal)
{
vmessage ("child terminated by signal %d %s",
s.signal, (s.coredump ? "(coredump)" : ""));
}
fork, new_process