Misc changes suggested by mib.
[kopensolaris-gnu/glibc.git] / manual / process.texi
1 @node Processes
2 @chapter Processes
3
4 @cindex process
5 @dfn{Processes} are the primitive units for allocation of system
6 resources.  Each process has its own address space and (usually) one
7 thread of control.  A process executes a program; you can have multiple
8 processes executing the same program, but each process has its own copy
9 of the program within its own address space and executes it
10 independently of the other copies.
11
12 @cindex child process
13 @cindex parent process
14 Processes are organized hierarchically.  Each process has a @dfn{parent
15 process} which explicitly arranged to create it.  The processes created
16 by a given parent are called its @dfn{child processes}.  A child
17 inherits many of its attributes from the parent process.
18
19 This chapter describes how a program can create, terminate, and control
20 child processes.  Actually, there are three distinct operations
21 involved: creating a new child process, causing the new process to
22 execute a program, and coordinating the completion of the child process
23 with the original program.
24
25 The @code{system} function provides a simple, portable mechanism for
26 running another program; it does all three steps automatically.  If you
27 need more control over the details of how this is done, you can use the
28 primitive functions to do each step individually instead.
29
30 @menu
31 * Running a Command::           The easy way to run another program.
32 * Process Creation Concepts::   An overview of the hard way to do it.
33 * Process Identification::      How to get the process ID of a process.
34 * Creating a Process::          How to fork a child process.
35 * Executing a File::            How to make a process execute another program.
36 * Process Completion::          How to tell when a child process has completed.
37 * Process Completion Status::   How to interpret the status value 
38                                  returned from a child process.
39 * BSD Wait Functions::          More functions, for backward compatibility.
40 * Process Creation Example::    A complete example program.
41 @end menu
42
43
44 @node Running a Command
45 @section Running a Command
46 @cindex running a command
47
48 The easy way to run another program is to use the @code{system}
49 function.  This function does all the work of running a subprogram, but
50 it doesn't give you much control over the details: you have to wait
51 until the subprogram terminates before you can do anything else.
52
53 @comment stdlib.h
54 @comment ANSI
55 @deftypefun int system (const char *@var{command})
56 @pindex sh
57 This function executes @var{command} as a shell command.  In the GNU C
58 library, it always uses the default shell @code{sh} to run the command.
59 In particular, it searches the directories in @code{PATH} to find
60 programs to execute.  The return value is @code{-1} if it wasn't
61 possible to create the shell process, and otherwise is the status of the
62 shell process.  @xref{Process Completion}, for details on how this
63 status code can be interpreted.
64
65 @pindex stdlib.h
66 The @code{system} function is declared in the header file
67 @file{stdlib.h}.
68 @end deftypefun
69
70 @strong{Portability Note:} Some C implementations may not have any
71 notion of a command processor that can execute other programs.  You can
72 determine whether a command processor exists by executing
73 @w{@code{system (NULL)}}; if the return value is nonzero, a command
74 processor is available.
75
76 The @code{popen} and @code{pclose} functions (@pxref{Pipe to a
77 Subprocess}) are closely related to the @code{system} function.  They
78 allow the parent process to communicate with the standard input and
79 output channels of the command being executed.
80
81 @node Process Creation Concepts
82 @section Process Creation Concepts
83
84 This section gives an overview of processes and of the steps involved in
85 creating a process and making it run another program.
86
87 @cindex process ID
88 @cindex process lifetime
89 Each process is named by a @dfn{process ID} number.  A unique process ID
90 is allocated to each process when it is created.  The @dfn{lifetime} of
91 a process ends when its termination is reported to its parent process;
92 at that time, all of the process resources, including its process ID,
93 are freed.
94
95 @cindex creating a process
96 @cindex forking a process
97 @cindex child process
98 @cindex parent process
99 Processes are created with the @code{fork} system call (so the operation
100 of creating a new process is sometimes called @dfn{forking} a process).
101 The @dfn{child process} created by @code{fork} is a copy of the original
102 @dfn{parent process}, except that it has its own process ID.
103
104 After forking a child process, both the parent and child processes
105 continue to execute normally.  If you want your program to wait for a
106 child process to finish executing before continuing, you must do this
107 explicitly after the fork operation, by calling @code{wait} or
108 @code{waitpid} (@pxref{Process Completion}).  These functions give you
109 limited information about why the child terminated---for example, its
110 exit status code.
111
112 A newly forked child process continues to execute the same program as
113 its parent process, at the point where the @code{fork} call returns.
114 You can use the return value from @code{fork} to tell whether the program
115 is running in the parent process or the child.
116
117 @cindex process image
118 Having several processes run the same program is only occasionally
119 useful.  But the child can execute another program using one of the
120 @code{exec} functions; see @ref{Executing a File}.  The program that the
121 process is executing is called its @dfn{process image}.  Starting
122 execution of a new program causes the process to forget all about its
123 previous process image; when the new program exits, the process exits
124 too, instead of returning to the previous process image.
125
126 @node Process Identification
127 @section Process Identification
128
129 The @code{pid_t} data type represents process IDs.  You can get the
130 process ID of a process by calling @code{getpid}.  The function
131 @code{getppid} returns the process ID of the parent of the current
132 process (this is also known as the @dfn{parent process ID}).  Your
133 program should include the header files @file{unistd.h} and
134 @file{sys/types.h} to use these functions.
135 @pindex sys/types.h
136 @pindex unistd.h
137
138 @comment sys/types.h
139 @comment POSIX.1
140 @deftp {Data Type} pid_t
141 The @code{pid_t} data type is a signed integer type which is capable
142 of representing a process ID.  In the GNU library, this is an @code{int}.
143 @end deftp
144
145 @comment unistd.h
146 @comment POSIX.1
147 @deftypefun pid_t getpid (void)
148 The @code{getpid} function returns the process ID of the current process.
149 @end deftypefun
150
151 @comment unistd.h
152 @comment POSIX.1
153 @deftypefun pid_t getppid (void)
154 The @code{getppid} function returns the process ID of the parent of the
155 current process.
156 @end deftypefun
157
158 @node Creating a Process
159 @section Creating a Process
160
161 The @code{fork} function is the primitive for creating a process.
162 It is declared in the header file @file{unistd.h}.
163 @pindex unistd.h
164
165 @comment unistd.h
166 @comment POSIX.1
167 @deftypefun pid_t fork (void)
168 The @code{fork} function creates a new process.
169
170 If the operation is successful, there are then both parent and child
171 processes and both see @code{fork} return, but with different values: it
172 returns a value of @code{0} in the child process and returns the child's
173 process ID in the parent process.
174
175 If process creation failed, @code{fork} returns a value of @code{-1} in
176 the parent process.  The following @code{errno} error conditions are
177 defined for @code{fork}:
178
179 @table @code
180 @item EAGAIN
181 There aren't enough system resources to create another process, or the
182 user already has too many processes running.
183
184 @item ENOMEM
185 The process requires more space than the system can supply.
186 @end table
187 @end deftypefun
188
189 The specific attributes of the child process that differ from the
190 parent process are:
191
192 @itemize @bullet
193 @item
194 The child process has its own unique process ID.
195
196 @item
197 The parent process ID of the child process is the process ID of its
198 parent process.
199
200 @item
201 The child process gets its own copies of the parent process's open file
202 descriptors.  Subsequently changing attributes of the file descriptors
203 in the parent process won't affect the file descriptors in the child,
204 and vice versa.  @xref{Control Operations}.  However, the file position
205 associated with each descriptor is shared by both processes;
206 @pxref{File Position}.
207
208 @item
209 The elapsed processor times for the child process are set to zero;
210 see @ref{Processor Time}.
211
212 @item
213 The child doesn't inherit file locks set by the parent process.
214 @c !!! flock locks shared
215 @xref{Control Operations}.
216
217 @item
218 The child doesn't inherit alarms set by the parent process.
219 @xref{Setting an Alarm}.
220
221 @item
222 The set of pending signals (@pxref{Delivery of Signal}) for the child
223 process is cleared.  (The child process inherits its mask of blocked
224 signals and signal actions from the parent process.)
225 @end itemize 
226
227
228 @comment unistd.h
229 @comment BSD
230 @deftypefun pid_t vfork (void)
231 The @code{vfork} function is similar to @code{fork} but on systems it
232 is more efficient; however, there are restrictions you must follow to
233 use it safely.
234
235 While @code{fork} makes a complete copy of the calling process's
236 address space and allows both the parent and child to execute
237 independently, @code{vfork} does not make this copy.  Instead, the
238 child process created with @code{vfork} shares its parent's address
239 space until it calls exits or one of the @code{exec} functions.  In the
240 meantime, the parent process suspends execution.
241
242 You must be very careful not to allow the child process created with
243 @code{vfork} to modify any global data or even local variables shared
244 with the parent.  Furthermore, the child process cannot return from (or
245 do a long jump out of) the function that called @code{vfork}!  This
246 would leave the parent process's control information very confused.  If
247 in doubt, use @code{fork} instead.
248
249 Some operating systems don't really implement @code{vfork}.  The GNU C
250 library permits you to use @code{vfork} on all systems, but actually
251 executes @code{fork} if @code{vfork} isn't available.  If you follow
252 the proper precautions for using @code{vfork}, your program will still
253 work even if the system uses @code{fork} instead.
254 @end deftypefun
255
256 @node Executing a File
257 @section Executing a File
258 @cindex executing a file
259 @cindex @code{exec} functions
260
261 This section describes the @code{exec} family of functions, for executing
262 a file as a process image.  You can use these functions to make a child
263 process execute a new program after it has been forked.
264
265 @pindex unistd.h
266 The functions in this family differ in how you specify the arguments,
267 but otherwise they all do the same thing.  They are declared in the
268 header file @file{unistd.h}.
269
270 @comment unistd.h
271 @comment POSIX.1
272 @deftypefun int execv (const char *@var{filename}, char *const @var{argv}@t{[]})
273 The @code{execv} function executes the file named by @var{filename} as a
274 new process image.
275
276 The @var{argv} argument is an array of null-terminated strings that is
277 used to provide a value for the @code{argv} argument to the @code{main}
278 function of the program to be executed.  The last element of this array
279 must be a null pointer.  By convention, the first element of this array
280 is the file name of the program sans directory names.  @xref{Program
281 Arguments}, for full details on how programs can access these arguments.
282
283 The environment for the new process image is taken from the
284 @code{environ} variable of the current process image; see
285 @ref{Environment Variables}, for information about environments.
286 @end deftypefun
287
288 @comment unistd.h
289 @comment POSIX.1
290 @deftypefun int execl (const char *@var{filename}, const char *@var{arg0}, @dots{})
291 This is similar to @code{execv}, but the @var{argv} strings are
292 specified individually instead of as an array.  A null pointer must be
293 passed as the last such argument.
294 @end deftypefun
295
296 @comment unistd.h
297 @comment POSIX.1
298 @deftypefun int execve (const char *@var{filename}, char *const @var{argv}@t{[]}, char *const @var{env}@t{[]})
299 This is similar to @code{execv}, but permits you to specify the environment
300 for the new program explicitly as the @var{env} argument.  This should
301 be an array of strings in the same format as for the @code{environ} 
302 variable; see @ref{Environment Access}.
303 @end deftypefun
304
305 @comment unistd.h
306 @comment POSIX.1
307 @deftypefun int execle (const char *@var{filename}, const char *@var{arg0}, char *const @var{env}@t{[]}, @dots{})
308 This is similar to @code{execl}, but permits you to specify the
309 environment for the new program explicitly.  The environment argument is
310 passed following the null pointer that marks the last @var{argv}
311 argument, and should be an array of strings in the same format as for
312 the @code{environ} variable.
313 @end deftypefun
314
315 @comment unistd.h
316 @comment POSIX.1
317 @deftypefun int execvp (const char *@var{filename}, char *const @var{argv}@t{[]})
318 The @code{execvp} function is similar to @code{execv}, except that it
319 searches the directories listed in the @code{PATH} environment variable
320 (@pxref{Standard Environment}) to find the full file name of a
321 file from @var{filename} if @var{filename} does not contain a slash.
322
323 This function is useful for executing system utility programs, because
324 it looks for them in the places that the user has chosen.  Shells use it
325 to run the commands that users type.
326 @end deftypefun
327
328 @comment unistd.h
329 @comment POSIX.1
330 @deftypefun int execlp (const char *@var{filename}, const char *@var{arg0}, @dots{})
331 This function is like @code{execl}, except that it performs the same
332 file name searching as the @code{execvp} function.
333 @end deftypefun
334
335 The size of the argument list and environment list taken together must
336 not be greater than @code{ARG_MAX} bytes.  @xref{General Limits}.  In
337 the GNU system, the size (which compares against @code{ARG_MAX})
338 includes, for each string, the number of characters in the string, plus
339 the size of a @code{char *}, plus one, rounded up to a multiple of the
340 size of a @code{char *}.  Other systems may have somewhat different
341 rules for counting.
342
343 These functions normally don't return, since execution of a new program
344 causes the currently executing program to go away completely.  A value
345 of @code{-1} is returned in the event of a failure.  In addition to the
346 usual file name syntax errors (@pxref{File Name Errors}), the following
347 @code{errno} error conditions are defined for these functions:
348
349 @table @code
350 @item E2BIG
351 The combined size of the new program's argument list and environment
352 list is larger than @code{ARG_MAX} bytes.  The GNU system has no
353 specific limit on the argument list size, so this error code cannot
354 result, but you may get @code{ENOMEM} instead if the arguments are too
355 big for available memory.
356
357 @item ENOEXEC
358 The specified file can't be executed because it isn't in the right format.
359
360 @item ENOMEM
361 Executing the specified file requires more storage than is available.
362 @end table
363
364 If execution of the new file succeeds, it updates the access time field
365 of the file as if the file had been read.  @xref{File Times}, for more
366 details about access times of files.
367
368 The point at which the file is closed again is not specified, but
369 is at some point before the process exits or before another process
370 image is executed.
371
372 Executing a new process image completely changes the contents of memory,
373 copying only the argument and environment strings to new locations.  But
374 many other attributes of the process are unchanged:
375
376 @itemize @bullet
377 @item
378 The process ID and the parent process ID.  @xref{Process Creation Concepts}.
379
380 @item
381 Session and process group membership.  @xref{Concepts of Job Control}.
382
383 @item
384 Real user ID and group ID, and supplementary group IDs.  @xref{Process
385 Persona}.
386
387 @item
388 Pending alarms.  @xref{Setting an Alarm}.
389
390 @item
391 Current working directory and root directory.  @xref{Working
392 Directory}.  In the GNU system, the root directory is not copied when
393 executing a setuid program; instead the system default root directory
394 is used for the new program.
395
396 @item
397 File mode creation mask.  @xref{Setting Permissions}.
398
399 @item
400 Process signal mask; see @ref{Process Signal Mask}.
401
402 @item
403 Pending signals; see @ref{Blocking Signals}.
404
405 @item
406 Elapsed processor time associated with the process; see @ref{Processor Time}.
407 @end itemize
408
409 If the set-user-ID and set-group-ID mode bits of the process image file
410 are set, this affects the effective user ID and effective group ID
411 (respectively) of the process.  These concepts are discussed in detail
412 in @ref{Process Persona}.
413
414 Signals that are set to be ignored in the existing process image are
415 also set to be ignored in the new process image.  All other signals are
416 set to the default action in the new process image.  For more
417 information about signals, see @ref{Signal Handling}.
418
419 File descriptors open in the existing process image remain open in the
420 new process image, unless they have the @code{FD_CLOEXEC}
421 (close-on-exec) flag set.  The files that remain open inherit all
422 attributes of the open file description from the existing process image,
423 including file locks.  File descriptors are discussed in @ref{Low-Level I/O}.
424
425 Streams, by contrast, cannot survive through @code{exec} functions,
426 because they are located in the memory of the process itself.  The new
427 process image has no streams except those it creates afresh.  Each of
428 the streams in the pre-@code{exec} process image has a descriptor inside
429 it, and these descriptors do survive through @code{exec} (provided that
430 they do not have @code{FD_CLOEXEC} set).  The new process image can
431 reconnect these to new streams using @code{fdopen} (@pxref{Descriptors
432 and Streams}).
433
434 @node Process Completion
435 @section Process Completion
436 @cindex process completion
437 @cindex waiting for completion of child process
438 @cindex testing exit status of child process
439
440 The functions described in this section are used to wait for a child
441 process to terminate or stop, and determine its status.  These functions
442 are declared in the header file @file{sys/wait.h}.
443 @pindex sys/wait.h
444
445 @comment sys/wait.h
446 @comment POSIX.1
447 @deftypefun pid_t waitpid (pid_t @var{pid}, int *@var{status-ptr}, int @var{options})
448 The @code{waitpid} function is used to request status information from a
449 child process whose process ID is @var{pid}.  Normally, the calling
450 process is suspended until the child process makes status information
451 available by terminating.
452
453 Other values for the @var{pid} argument have special interpretations.  A
454 value of @code{-1} or @code{WAIT_ANY} requests status information for
455 any child process; a value of @code{0} or @code{WAIT_MYPGRP} requests
456 information for any child process in the same process group as the
457 calling process; and any other negative value @minus{} @var{pgid}
458 requests information for any child process whose process group ID is
459 @var{pgid}.
460
461 If status information for a child process is available immediately, this
462 function returns immediately without waiting.  If more than one eligible
463 child process has status information available, one of them is chosen
464 randomly, and its status is returned immediately.  To get the status
465 from the other eligible child processes, you need to call @code{waitpid}
466 again.
467
468 The @var{options} argument is a bit mask.  Its value should be the
469 bitwise OR (that is, the @samp{|} operator) of zero or more of the
470 @code{WNOHANG} and @code{WUNTRACED} flags.  You can use the
471 @code{WNOHANG} flag to indicate that the parent process shouldn't wait;
472 and the @code{WUNTRACED} flag to request status information from stopped
473 processes as well as processes that have terminated.
474
475 The status information from the child process is stored in the object
476 that @var{status-ptr} points to, unless @var{status-ptr} is a null pointer.
477
478 The return value is normally the process ID of the child process whose
479 status is reported.  If the @code{WNOHANG} option was specified and no
480 child process is waiting to be noticed, the value is zero.  A value of
481 @code{-1} is returned in case of error.  The following @code{errno}
482 error conditions are defined for this function:
483
484 @table @code
485 @item EINTR
486 The function was interrupted by delivery of a signal to the calling
487 process.  @xref{Interrupted Primitives}.
488
489 @item ECHILD
490 There are no child processes to wait for, or the specified @var{pid}
491 is not a child of the calling process.
492
493 @item EINVAL
494 An invalid value was provided for the @var{options} argument.
495 @end table
496 @end deftypefun
497
498 These symbolic constants are defined as values for the @var{pid} argument
499 to the @code{waitpid} function.
500
501 @comment Extra blank lines make it look better.
502 @table @code
503 @item WAIT_ANY
504
505 This constant macro (whose value is @code{-1}) specifies that
506 @code{waitpid} should return status information about any child process.
507
508
509 @item WAIT_MYPGRP
510 This constant (with value @code{0}) specifies that @code{waitpid} should
511 return status information about any child process in the same process
512 group as the calling process.
513 @end table
514
515 These symbolic constants are defined as flags for the @var{options}
516 argument to the @code{waitpid} function.  You can bitwise-OR the flags
517 together to obtain a value to use as the argument.
518
519 @table @code
520 @item WNOHANG
521
522 This flag specifies that @code{waitpid} should return immediately
523 instead of waiting, if there is no child process ready to be noticed.
524
525 @item WUNTRACED
526
527 This flag specifies that @code{waitpid} should report the status of any
528 child processes that have been stopped as well as those that have
529 terminated.
530 @end table
531
532 @comment sys/wait.h
533 @comment POSIX.1
534 @deftypefun pid_t wait (int *@var{status-ptr})
535 This is a simplified version of @code{waitpid}, and is used to wait
536 until any one child process terminates.  The call:
537
538 @smallexample
539 wait (&status)
540 @end smallexample
541
542 @noindent
543 is exactly equivalent to:
544
545 @smallexample
546 waitpid (-1, &status, 0)
547 @end smallexample
548 @end deftypefun
549
550 Here's an example of how to use @code{waitpid} to get the status from
551 all child processes that have terminated, without ever waiting.  This
552 function is designed to be a handler for @code{SIGCHLD}, the signal that
553 indicates that at least one child process has terminated.
554
555 @smallexample
556 @group
557 void
558 sigchld_handler (int signum)
559 @{
560   int pid;
561   int status;
562   while (1)
563     @{
564       pid = waitpid (WAIT_ANY, &status, WNOHANG);
565       if (pid < 0)
566         @{
567           perror ("waitpid");
568           break;
569         @}
570       if (pid == 0)
571         break;
572       notice_termination (pid, status);
573     @}
574 @}
575 @end group
576 @end smallexample
577
578 @node Process Completion Status
579 @section Process Completion Status
580
581 If the exit status value (@pxref{Program Termination}) of the child
582 process is zero, then the status value reported by @code{waitpid} or
583 @code{wait} is also zero.  You can test for other kinds of information
584 encoded in the returned status value using the following macros.
585 These macros are defined in the header file @file{sys/wait.h}.
586 @pindex sys/wait.h
587
588 @comment sys/wait.h
589 @comment POSIX.1
590 @deftypefn Macro int WIFEXITED (int @var{status})
591 This macro returns a nonzero value if the child process terminated
592 normally with @code{exit} or @code{_exit}.
593 @end deftypefn
594
595 @comment sys/wait.h
596 @comment POSIX.1
597 @deftypefn Macro int WEXITSTATUS (int @var{status})
598 If @code{WIFEXITED} is true of @var{status}, this macro returns the
599 low-order 8 bits of the exit status value from the child process.
600 @xref{Exit Status}.
601 @end deftypefn
602
603 @comment sys/wait.h
604 @comment POSIX.1
605 @deftypefn Macro int WIFSIGNALED (int @var{status})
606 This macro returns a nonzero value if the child process terminated
607 because it received a signal that was not handled.
608 @xref{Signal Handling}.
609 @end deftypefn
610
611 @comment sys/wait.h
612 @comment POSIX.1
613 @deftypefn Macro int WTERMSIG (int @var{status})
614 If @code{WIFSIGNALED} is true of @var{status}, this macro returns the
615 signal number of the signal that terminated the child process.
616 @end deftypefn
617
618 @comment sys/wait.h
619 @comment BSD
620 @deftypefn Macro int WCOREDUMP (int @var{status})
621 This macro returns a nonzero value if the child process terminated
622 and produced a core dump.
623 @end deftypefn
624
625 @comment sys/wait.h
626 @comment POSIX.1
627 @deftypefn Macro int WIFSTOPPED (int @var{status})
628 This macro returns a nonzero value if the child process is stopped.
629 @end deftypefn
630
631 @comment sys/wait.h
632 @comment POSIX.1
633 @deftypefn Macro int WSTOPSIG (int @var{status})
634 If @code{WIFSTOPPED} is true of @var{status}, this macro returns the
635 signal number of the signal that caused the child process to stop.
636 @end deftypefn
637
638
639 @node BSD Wait Functions
640 @section BSD Process Wait Functions
641
642 The GNU library also provides these related facilities for compatibility
643 with BSD Unix.  BSD uses the @code{union wait} data type to represent
644 status values rather than an @code{int}.  The two representations are
645 actually interchangeable; they describe the same bit patterns.  The GNU
646 C Library defines macros such as @code{WEXITSTATUS} so that they will
647 work on either kind of object, and the @code{wait} function is defined
648 to accept either type of pointer as its @var{status-ptr} argument.
649
650 These functions are declared in @file{sys/wait.h}.
651 @pindex sys/wait.h
652
653 @comment sys/wait.h
654 @comment BSD
655 @deftp {Data Type} {union wait}
656 This data type represents program termination status values.  It has
657 the following members:
658
659 @table @code
660 @item int w_termsig
661 The value of this member is the same as the result of the
662 @code{WTERMSIG} macro.
663
664 @item int w_coredump
665 The value of this member is the same as the result of the
666 @code{WCOREDUMP} macro.
667
668 @item int w_retcode
669 The value of this member is the same as the result of the
670 @code{WEXITSTATUS} macro.
671
672 @item int w_stopsig
673 The value of this member is the same as the result of the
674 @code{WSTOPSIG} macro.
675 @end table
676
677 Instead of accessing these members directly, you should use the
678 equivalent macros.
679 @end deftp
680
681 @comment sys/wait.h
682 @comment BSD
683 @deftypefun pid_t wait3 (union wait *@var{status-ptr}, int @var{options}, struct rusage *@var{usage})
684 If @var{usage} is a null pointer, @code{wait3} is equivalent to
685 @code{waitpid (-1, @var{status-ptr}, @var{options})}.
686
687 If @var{usage} is not null, @code{wait3} stores usage figures for the
688 child process in @code{*@var{rusage}} (but only if the child has
689 terminated, not if it has stopped).  @xref{Resource Usage}.
690 @end deftypefun
691
692 @comment sys/wait.h
693 @comment BSD
694 @deftypefun pid_t wait4 (pid_t @var{pid}, union wait *@var{status-ptr}, int @var{options}, struct rusage *@var{usage})
695 If @var{usage} is a null pointer, @code{wait4} is equivalent to
696 @code{waitpid (@var{pid}, @var{status-ptr}, @var{options})}.
697
698 If @var{usage} is not null, @code{wait4} stores usage figures for the
699 child process in @code{*@var{rusage}} (but only if the child has
700 terminated, not if it has stopped).  @xref{Resource Usage}.
701 @end deftypefun
702
703 @node Process Creation Example
704 @section Process Creation Example
705
706 Here is an example program showing how you might write a function
707 similar to the built-in @code{system}.  It executes its @var{command}
708 argument using the equivalent of @samp{sh -c @var{command}}.
709
710 @smallexample
711 #include <stddef.h>
712 #include <stdlib.h>
713 #include <unistd.h>
714 #include <sys/types.h>
715 #include <sys/wait.h>
716
717 /* @r{Execute the command using this shell program.}  */
718 #define SHELL "/bin/sh"
719
720 @group
721 int 
722 my_system (const char *command)
723 @{
724   int status;
725   pid_t pid;
726 @end group
727
728   pid = fork ();
729   if (pid == 0)
730     @{
731       /* @r{This is the child process.  Execute the shell command.} */
732       execl (SHELL, SHELL, "-c", command, NULL);
733       _exit (EXIT_FAILURE);
734     @}
735   else if (pid < 0)
736     /* @r{The fork failed.  Report failure.}  */
737     status = -1;
738   else
739     /* @r{This is the parent process.  Wait for the child to complete.}  */
740     if (waitpid (pid, &status, 0) != pid)
741       status = -1;
742   return status;
743 @}
744 @end smallexample
745
746 @comment Yes, this example has been tested.
747
748 There are a couple of things you should pay attention to in this
749 example.
750
751 Remember that the first @code{argv} argument supplied to the program
752 represents the name of the program being executed.  That is why, in the
753 call to @code{execl}, @code{SHELL} is supplied once to name the program
754 to execute and a second time to supply a value for @code{argv[0]}.  
755
756 The @code{execl} call in the child process doesn't return if it is
757 successful.  If it fails, you must do something to make the child
758 process terminate.  Just returning a bad status code with @code{return}
759 would leave two processes running the original program.  Instead, the
760 right behavior is for the child process to report failure to its parent
761 process.
762
763 Call @code{_exit} to accomplish this.  The reason for using @code{_exit}
764 instead of @code{exit} is to avoid flushing fully buffered streams such
765 as @code{stdout}.  The buffers of these streams probably contain data
766 that was copied from the parent process by the @code{fork}, data that
767 will be output eventually by the parent process.  Calling @code{exit} in
768 the child would output the data twice.  @xref{Termination Internals}.