fork

 SYNOPSIS
  Create a new process via the fork system function

 USAGE
  Int_Type fork ()

 DESCRIPTION
 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.

 EXAMPLE
 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;
         }
     }


 SEE ALSO
  waitpid, execv, execvp, execve, _exit, system

--------------------------------------------------------------

execve, execv, execvp

 SYNOPSIS
  Execute a new process

 USAGE
  Int_Type execve(path, argv[], envp[])

  Int_Type execvp(path, argv[])}
  Int_Type execv(path, argv[])}


 DESCRIPTION
  The `execv' family of functions overlay the current process
  with a new process that corresponds 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
  correspond to the argument list used when invoking the program.  For
  example, if the invoked program is a C program, the `argv'
  parameter will correspond to the C program's argv-list.

  The `execve' function takes an array of strings that will be
  used to initialize the environment of the overlayed program.

  The `execvp' function will mimick the actions `/bin/sh' when
  searching for the executable file.

 NOTES
  These function are wrappers around the corresponding system library
  functions.  See the system documentation for more information.

 SEE ALSO
  execve, execvp, system, fork, _exit

--------------------------------------------------------------

_exit

 SYNOPSIS
  Exit the current processes

 USAGE
  _exit(Int_Type status)

 DESCRIPTION
  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.

 SEE ALSO
  fork, execv, execvp, execve, waitpid, exit

--------------------------------------------------------------

waitpid

 SYNOPSIS
  Wait for a specified process

 USAGE
  Struct_Type waitpid (pid, options)

 DESCRIPTION
  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)


 EXAMPLE

   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)" : ""));
     }


 SEE ALSO
  fork, new_process

--------------------------------------------------------------
