Next Previous Contents

5. Fork Module

The fork module contains several low-level functions that may be used for subprocess creation. Use require("fork") to load it.

5.1 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

5.2 execv

Synopsis

Execute a new process

Usage

Int_Type execv(path, argv[])

Description

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.

Notes

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.

See Also

execvp, execve, system, fork, _exit

5.3 execve

Synopsis

Execute a new process

Usage

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

Description

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.

Notes

This function is a wrapper around the corresponding system library function. See the system-specific documentation for more information.

See Also

execv, execvp, system, fork, _exit

5.4 execvp

Synopsis

Execute a new process

Usage

Int_Type execvp(pgm, argv[])

Description

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.

Notes

This function is a wrapper around the corresponding system library function. See the system-specific documentation for more information.

See Also

execv, execve, system, fork, _exit

5.5 _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

5.6 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


Next Previous Contents