1fork
2
3 SYNOPSIS
4  Create a new process via the fork system function
5
6 USAGE
7  Int_Type fork ()
8
9 DESCRIPTION
10 The `fork' function creates a new child process via the
11 `fork' system function.  See the approriate documentation for
12 the actual semantics involved such as what is preserved in the child
13 process.  Upon sucess, the function returns a value that is greater
14 than 0 to the parent process that represents the child process's id.
15 It will return 0 to the child process.  If the fork function fails, a
16 value of -1 will be returned and `errno' set accordingly.
17
18 EXAMPLE
19 The following example creates a child process to invoke the ``ls''
20 command on a Unix system.  It also illustrates the low-level nature
21 of the `fork' and related system calls.
22
23    define ls ()
24    {
25       variable pid = fork ();
26       if (pid == -1)
27         throw OSError, "fork failed: " + errno_string(errno);
28
29       if ((pid == 0)
30            && (-1 == execvp ("ls", ["ls", "-l"])))
31         {
32           () = fprintf (stderr, "execvp failed: " + errno_string(errno));
33           _exit (1);
34         }
35
36       forever
37         {
38           variable status = waitpid (pid, 0);
39           if (status == NULL)
40             {
41               if (errno == EINTR) continue;
42               throw OSError, "waitpid failed: " + errno_string(errno);
43             }
44           return status.exit_status;
45         }
46     }
47
48
49 SEE ALSO
50  waitpid, execv, execvp, execve, _exit, system
51
52--------------------------------------------------------------
53
54execve, execv, execvp
55
56 SYNOPSIS
57  Execute a new process
58
59 USAGE
60  Int_Type execve(path, argv[], envp[])
61
62  Int_Type execvp(path, argv[])}
63  Int_Type execv(path, argv[])}
64
65
66 DESCRIPTION
67  The `execv' family of functions overlay the current process
68  with a new process that corresponds to the program specified by the
69  `path' argument.  If for some reason the function fails, a
70  value of -1 will be returned with `errno' set accordingly.
71  Normally the function will not return.
72
73  The `argv' parameter is an array of strings that will
74  correspond to the argument list used when invoking the program.  For
75  example, if the invoked program is a C program, the `argv'
76  parameter will correspond to the C program's argv-list.
77
78  The `execve' function takes an array of strings that will be
79  used to initialize the environment of the overlayed program.
80
81  The `execvp' function will mimick the actions `/bin/sh' when
82  searching for the executable file.
83
84 NOTES
85  These function are wrappers around the corresponding system library
86  functions.  See the system documentation for more information.
87
88 SEE ALSO
89  execve, execvp, system, fork, _exit
90
91--------------------------------------------------------------
92
93_exit
94
95 SYNOPSIS
96  Exit the current processes
97
98 USAGE
99  _exit(Int_Type status)
100
101 DESCRIPTION
102  Like the related `exit' function, `_exit' may be used to
103  terminate the current process.  One of the differences between the two
104  functions is that the `_exit' will not invoke various ``atexit''
105  handlers that are normally run when a program is terminated.  See
106  the system-specific C runtime library documentation for more
107  information about this function.
108
109  The main use of the `_exit' function is after the failure of
110  one of the `execv' functions in a child process.
111
112 SEE ALSO
113  fork, execv, execvp, execve, waitpid, exit
114
115--------------------------------------------------------------
116
117waitpid
118
119 SYNOPSIS
120  Wait for a specified process
121
122 USAGE
123  Struct_Type waitpid (pid, options)
124
125 DESCRIPTION
126  The `waitpid' function will cause the calling process to wait
127  for the child process whose process id is `pid' to change its
128  state, e.g., exit.  It returns information about the process in the
129  form of a structure with the following fields:
130
131    pid           The process-id of the child process, 0 if the process
132                    has not changed state.
133    exited        Non-zero if the child exited normally.
134    exit_status   The exit status of the child.  This field is
135                    meaninful only if the exited field is non-zero.
136    signal        Non-zero of the child was terminated by a signal.
137                    The value of this field is that of the signal.
138    coredump      Non-zero if the child produced a core-dump as the
139                    result of termination by a signal.
140    stopped       Non-zero if the child was stopped via a signal.  The
141                    value is that of the signal that stopped it.
142    continued     Non-zero if the process was continued.
143
144
145  Upon error, the function will return NULL and set `errno'
146  accordingly.
147
148  The value of the `options' parameter is the bitwise-or of one
149  of the following values:
150
151    WNOHANG      causes waitpid to return immediately if the child has
152                  not terminated.  In this case, the value of the pid
153                  field will be 0 if the child is still running.
154
155    WUNTRACED    (see semantics in the OS documentation)
156    WCONTINUED   (see semantics in the OS documentation)
157
158
159 EXAMPLE
160
161   s = waitpid (pid, WNOHANG);
162   if (s == NULL)
163     throw OSError, "waitpid failed: " + errno_string ();
164   if (s.pid == 0)
165     message ("The child is still running");
166   else if (s.exited)
167     vmessage ("child exited with status %d", s.exit_status);
168   else if (s.signal)
169     {
170        vmessage ("child terminated by signal %d %s",
171                  s.signal, (s.coredump ? "(coredump)" : ""));
172     }
173
174
175 SEE ALSO
176  fork, new_process
177
178--------------------------------------------------------------
179