d47a91a3390ee135fe864fb1b7b3fb5abd39fd1f
[kopensolaris-gnu/glibc.git] / manual / =process.texinfo
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 Processes are organized hierarchically.  Child processes are created by
13 a parent process, and inherit many of their attributes from the parent
14 process.
15
16 This chapter describes how a program can create, terminate, and control
17 child processes.
18
19 @menu
20 * Program Arguments::           Parsing the command-line arguments to
21                                  a program.
22 * Environment Variables::       How to access parameters inherited from
23                                  a parent process.
24 * Program Termination::         How to cause a process to terminate and
25                                  return status information to its parent.
26 * Creating New Processes::      Running other programs.
27 @end menu
28
29
30 @node Program Arguments
31 @section Program Arguments
32 @cindex program arguments
33 @cindex command line arguments
34
35 @cindex @code{main} function
36 When your C program starts, it begins by executing the function called
37 @code{main}.  You can define @code{main} either to take no arguments,
38 or to take two arguments that represent the command line arguments
39 to the program, like this:
40
41 @example
42 int main (int @var{argc}, char *@var{argv}[])
43 @end example
44
45 @cindex argc (program argument count)
46 @cindex argv (program argument vector)
47 The command line arguments are the whitespace-separated tokens typed by
48 the user to the shell in invoking the program.  The value of the
49 @var{argc} argument is the number of command line arguments.  The
50 @var{argv} argument is a vector of pointers to @code{char}; sometimes it
51 is also declared as @samp{char **@var{argv}}.  The elements of
52 @var{argv} are the individual command line argument strings.  By
53 convention, @samp{@var{argv}[0]} is the file name of the program being
54 run, and @samp{@var{argv}[@var{argc}]} is a null pointer.
55
56 If the syntax for the command line arguments to your program is simple
57 enough, you can simply pick the arguments off from @var{argv} by hand.
58 But unless your program takes a fixed number of arguments, or all of the
59 arguments are interpreted in the same way (as file names, for example),
60 you are usually better off using @code{getopt} to do the parsing.
61
62 @menu
63 * Program Argument Syntax Conventions::         By convention, program
64                                                  options are specified by a
65                                                  leading hyphen.
66 * Parsing Program Arguments::                   The @code{getopt} function.
67 * Example of Parsing Program Arguments::        An example of @code{getopt}.
68 @end menu
69
70 @node Program Argument Syntax Conventions
71 @subsection Program Argument Syntax Conventions
72 @cindex program argument syntax
73 @cindex syntax, for program arguments
74 @cindex command argument syntax
75
76 The @code{getopt} function decodes options following the usual
77 conventions for POSIX utilities:
78
79 @itemize @bullet
80 @item
81 Arguments are options if they begin with a hyphen delimiter (@samp{-}).
82
83 @item
84 Multiple options may follow a hyphen delimiter in a single token if
85 the options do not take arguments.  Thus, @samp{-abc} is equivalent to
86 @samp{-a -b -c}.
87
88 @item
89 Option names are single alphanumeric (as for @code{isalnum};
90 see @ref{Classification of Characters}).
91
92 @item
93 Certain options require an argument.  For example, the @samp{-o} 
94 command of the ld command requires an argument---an output file name.
95
96 @item
97 An option and its argument may or may appear as separate tokens.  (In
98 other words, the whitespace separating them is optional.)  Thus,
99 @samp{-o foo} and @samp{-ofoo} are equivalent.
100
101 @item
102 Options typically precede other non-option arguments.
103
104 The implementation of @code{getopt} in the GNU C library normally makes
105 it appear as if all the option arguments were specified before all the
106 non-option arguments for the purposes of parsing, even if the user of
107 your program intermixed option and non-option arguments.  It does this
108 by reordering the elements of the @var{argv} array.  This behavior is
109 nonstandard; if you want to suppress it, define the
110 @code{_POSIX_OPTION_ORDER} environment variable.  @xref{Standard
111 Environment Variables}.
112
113 @item
114 The argument @samp{--} terminates all options; any following arguments
115 are treated as non-option arguments, even if they begin with a hyphen.
116
117 @item
118 A token consisting of a single hyphen character is interpreted as an
119 ordinary non-option argument.  By convention, it is used to specify
120 input from or output to the standard input and output streams.
121
122 @item
123 Options may be supplied in any order, or appear multiple times.  The
124 interpretation is left up to the particular application program.
125 @end itemize
126
127 @node Parsing Program Arguments
128 @subsection Parsing Program Arguments
129 @cindex program arguments, parsing
130 @cindex command arguments, parsing
131 @cindex parsing program arguments
132
133 Here are the details about how to call the @code{getopt} function.  To
134 use this facility, your program must include the header file
135 @file{unistd.h}.
136 @pindex unistd.h
137
138 @comment unistd.h
139 @comment POSIX.2
140 @deftypevar int opterr
141 If the value of this variable is nonzero, then @code{getopt} prints an
142 error message to the standard error stream if it encounters an unknown
143 option character or an option with a missing required argument.  This is
144 the default behavior.  If you set this variable to zero, @code{getopt}
145 does not print any messages, but it still returns @code{?} to indicate
146 an error.
147 @end deftypevar
148
149 @comment unistd.h
150 @comment POSIX.2
151 @deftypevar int optopt
152 When @code{getopt} encounters an unknown option character or an option
153 with a missing required argument, it stores that option character in
154 this variable.  You can use this for providing your own diagnostic
155 messages.
156 @end deftypevar
157
158 @comment unistd.h
159 @comment POSIX.2
160 @deftypevar int optind
161 This variable is set by @code{getopt} to the index of the next element
162 of the @var{argv} array to be processed.  Once @code{getopt} has found
163 all of the option arguments, you can use this variable to determine
164 where the remaining non-option arguments begin.  The initial value of
165 this variable is @code{1}.
166 @end deftypevar
167
168 @comment unistd.h
169 @comment POSIX.2
170 @deftypevar {char *} optarg
171 This variable is set by @code{getopt} to point at the value of the
172 option argument, for those options that accept arguments.
173 @end deftypevar
174
175 @comment unistd.h
176 @comment POSIX.2
177 @deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options})
178 The @code{getopt} function gets the next option argument from the
179 argument list specified by the @var{argv} and @var{argc} arguments.
180 Normally these arguments' values come directly from the arguments of
181 @code{main}.
182
183 The @var{options} argument is a string that specifies the option
184 characters that are valid for this program.  An option character in this
185 string can be followed by a colon (@samp{:}) to indicate that it takes a
186 required argument.
187
188 If the @var{options} argument string begins with a hyphen (@samp{-}), this
189 is treated specially.  It permits arguments without an option to be
190 returned as if they were associated with option character @samp{\0}.
191
192 The @code{getopt} function returns the option character for the next
193 command line option.  When no more option arguments are available, it
194 returns @code{-1}.  There may still be more non-option arguments; you
195 must compare the external variable @code{optind} against the @var{argv}
196 parameter to check this.
197
198 If the options has an argument, @code{getopt} returns the argument by
199 storing it in the varables @var{optarg}.  You don't ordinarily need to
200 copy the @code{optarg} string, since it is a pointer into the original
201 @var{argv} array, not into a static area that might be overwritten.
202
203 If @code{getopt} finds an option character in @var{argv} that was not
204 included in @var{options}, or a missing option argument, it returns
205 @samp{?} and sets the external variable @code{optopt} to the actual
206 option character.  In addition, if the external variable @code{opterr}
207 is nonzero, @code{getopt} prints an error message.
208 @end deftypefun
209
210 @node Example of Parsing Program Arguments
211 @subsection Example of Parsing Program Arguments
212
213 Here is an example showing how @code{getopt} is typically used.  The
214 key points to notice are:
215
216 @itemize @bullet
217 @item
218 Normally, @code{getopt} is called in a loop.  When @code{getopt} returns
219 @code{-1}, indicating no more options are present, the loop terminates.
220
221 @item
222 A @code{switch} statement is used to dispatch on the return value from
223 @code{getopt}.  In typical use, each case just sets a variable that
224 is used later in the program.
225
226 @item
227 A second loop is used to process the remaining non-option arguments.
228 @end itemize
229
230 @example
231 #include <unistd.h>
232 #include <stdio.h>
233
234 int
235 main (int argc, char **argv)
236 @{
237   int aflag = 0;
238   int bflag = 0;
239   char *cvalue = NULL;
240   int index;
241   int c;
242   opterr = 0;
243
244   while ((c = getopt (argc, argv, "abc:")) >= 0)
245     switch (c) @{
246     case 'a':
247       aflag = 1;
248       break;
249     case 'b':
250       bflag = 1;
251       break;
252     case 'c':
253       cvalue = optarg;
254       break;
255     case '?':
256       if (isprint (optopt))
257         fprintf (stderr, "Unknown option %c.\n", optopt);
258       else
259         fprintf (stderr, "Unknown option character `\\x%x'", optopt);
260       return -1;
261     default:
262       abort ();
263       return -1;
264     @}
265
266   printf ("aflag = %d, bflag = %d, cvalue = %s\n", aflag, bflag, cvalue);
267
268   for (index = optind; index < argc; index++)
269     printf ("Non-option argument %s\n", argv[index]);
270   return 0;
271 @}
272 @end example
273
274 Here are some examples showing what this program prints with different
275 combinations of arguments:
276
277 @example
278 % testopt
279 aflag = 0, bflag = 0, cvalue = (null)
280
281 % testopt -a -b
282 aflag = 1, bflag = 1, cvalue = (null)
283
284 % testopt -ab
285 aflag = 1, bflag = 1, cvalue = (null)
286
287 % testopt -c foo
288 aflag = 0, bflag = 0, cvalue = foo
289
290 % testopt -cfoo
291 aflag = 0, bflag = 0, cvalue = foo
292
293 % testopt arg1
294 aflag = 0, bflag = 0, cvalue = (null)
295 Non-option argument arg1
296
297 % testopt -a arg1
298 aflag = 1, bflag = 0, cvalue = (null)
299 Non-option argument arg1
300
301 % testopt -c foo arg1
302 aflag = 0, bflag = 0, cvalue = foo
303 Non-option argument arg1
304
305 % testopt -a -- -b
306 aflag = 1, bflag = 0, cvalue = (null)
307 Non-option argument -b
308
309 % testopt -a -
310 aflag = 1, bflag = 0, cvalue = (null)
311 Non-option argument -
312 @end example
313
314 @node Environment Variables
315 @section Environment Variables
316
317 @cindex environment variable
318 When a program is executed, it receives information about the context in
319 which it was invoked in two ways.  The first mechanism uses the
320 @var{argv} and @var{argc} arguments to its @code{main} function, and is
321 discussed in @ref{Program Arguments}.  The second mechanism is
322 uses @dfn{environment variables} and is discussed in this section.
323
324 The @var{argv} mechanism is typically used to pass command-line
325 arguments specific to the particular program being invoked.  The
326 environment, on the other hand, keeps track of information that is
327 shared by many programs, changes infrequently, and that is less
328 frequently accessed.
329
330 The environment variables discussed in this section are the same
331 environment variables that you set using the assignments and the
332 @code{export} command in the shell.  Programs executed from the shell
333 inherit all of the environment variables from the shell.
334
335 @cindex environment
336 Standard environment variables are used for information about the user's
337 home directory, terminal type, current locale, and so on; you can define
338 additional variables for other purposes.  The set of all environment
339 variables that have values is collectively known as the
340 @dfn{environment}.
341
342 Names of environment variables are case-sensitive and must not contain
343 the character @samp{=}.  System-defined environment variables are
344 invariably uppercase.
345
346 The values of environment variables can be anything that can be
347 represented as a string.  A value must not contain an embedded null
348 character, since this is assumed to terminate the string.
349
350
351 @menu
352 * Environment Access::                  How to get and set the values of
353                                          environment variables.
354 * Standard Environment Variables::      These environment variables have
355                                          standard interpretations.
356 @end menu
357
358 @node Environment Access
359 @subsection Environment Access
360 @cindex environment access
361 @cindex environment representation
362
363 The value of an environment variable can be accessed with the
364 @code{getenv} function.  This is declared in the header file
365 @file{stdlib.h}.
366 @pindex stdlib.h
367
368 @comment stdlib.h
369 @comment ANSI
370 @deftypefun {char *} getenv (const char *@var{name})
371 This function returns a string that is the value of the environment
372 variable @var{name}.  You must not modify this string.  In some systems
373 not using the GNU library, it might be overwritten by subsequent calls
374 to @code{getenv} (but not by any other library function).  If the
375 environment variable @var{name} is not defined, the value is a null
376 pointer.
377 @end deftypefun
378
379
380 @comment stdlib.h
381 @comment SVID
382 @deftypefun int putenv (const char *@var{string})
383 The @code{putenv} function adds or removes definitions from the environment.
384 If the @var{string} is of the form @samp{@var{name}=@var{value}}, the
385 definition is added to the environment.  Otherwise, the @var{string} is
386 interpreted as the name of an environment variable, and any definition
387 for this variable in the environment is removed.
388
389 The GNU library provides this function for compatibility with SVID; it
390 may not be available in other systems.
391 @end deftypefun
392
393 You can deal directly with the underlying representation of environment
394 objects to add more variables to the environment (for example, to
395 communicate with another program you are about to execute; see
396 @ref{Executing a File}).  
397
398 @comment unistd.h
399 @comment POSIX.1
400 @deftypevar {char **} environ
401 The environment is represented as an array of strings.  Each string is
402 of the format @samp{@var{name}=@var{value}}.  The order in which
403 strings appear in the environment is not significant, but the same
404 @var{name} must not appear more than once.  The last element of the
405 array is a null pointer.
406
407 This variable is not declared in any header file, but if you declare it
408 in your own program as @code{extern}, the right thing will happen.
409
410 If you just want to get the value of an environment variable, use
411 @code{getenv}.
412 @end deftypevar
413
414 @node Standard Environment Variables
415 @subsection Standard Environment Variables
416 @cindex standard environment variables
417
418 These environment variables have standard meanings.
419 This doesn't mean that they are always present in the
420 environment, though; it just means that if these variables @emph{are}
421 present, they have these meanings, and that you shouldn't try to use
422 these environment variable names for some other purpose.
423
424 @table @code
425 @item HOME
426 @cindex HOME environment variable
427 @cindex home directory
428 This is a string representing the user's @dfn{home directory}, or
429 initial default working directory.  @xref{User Database}, for a
430 more secure way of determining this information.
431
432 @comment RMS says to explay why HOME is better, but I don't know why.
433
434 @item LOGNAME
435 @cindex LOGNAME environment variable
436 This is the name that the user used to log in.  Since the value in the
437 environment can be tweaked arbitrarily, this is not a reliable way to
438 identify the user who is running a process; a function like
439 @code{getlogin} (@pxref{User Identification Functions}) is better for
440 that purpose.
441
442 @comment RMS says to explay why LOGNAME is better, but I don't know why.
443
444 @item PATH
445 @cindex PATH environment variable
446 A @dfn{path} is a sequence of directory names which is used for
447 searching for a file.  The variable @var{PATH} holds a path The
448 @code{execlp} and @code{execvp} functions (@pxref{Executing a File})
449 uses this environment variable, as do many shells and other utilities
450 which are implemented in terms of those functions.
451
452 The syntax of a path is a sequence of directory names separated by
453 colons.  An empty string instead of a directory name stands for the 
454 current directory.  (@xref{Working Directory}.)
455
456 A typical value for this environment variable might be a string like:
457
458 @example
459 .:/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local:/usr/local/bin
460 @end example
461
462 This means that if the user tries to execute a program named @code{foo},
463 the system will look for files named @file{./foo}, @file{/bin/foo},
464 @file{/etc/foo}, and so on.  The first of these files that exists is
465 the one that is executed.
466
467 @item TERM
468 @cindex TERM environment variable
469 This specifies the kind of terminal that is receiving program output.
470 Some programs can make use of this information to take advantage of
471 special escape sequences or terminal modes supported by particular kinds
472 of terminals.  Many programs which use the termcap library
473 (@pxref{Finding a Terminal Description,Find,,termcap,The Termcap Library
474 Manual}) use the @code{TERM} environment variable, for example.
475
476 @item TZ
477 @cindex TZ environment variable
478 This specifies the time zone.  @xref{Time Zone}, for information about
479 the format of this string and how it is used.
480
481 @item LANG
482 @cindex LANG environment variable
483 This specifies the default locale to use for attribute categories where
484 neither @code{LC_ALL} nor the specific environment variable for that
485 category is set.  @xref{Locales}, for more information about
486 locales.
487
488 @item LC_ALL
489 @cindex LC_ALL environment variable
490 This is similar to the @code{LANG} environment variable.  However, its
491 value takes precedence over any values provided for the individual
492 attribute category environment variables, or for the @code{LANG}
493 environment variable.
494
495 @item LC_COLLATE
496 @cindex LC_COLLATE environment variable
497 This specifies what locale to use for string sorting.
498
499 @item LC_CTYPE
500 @cindex LC_CTYPE environment variable
501 This specifies what locale to use for character sets and character
502 classification.
503
504 @item LC_MONETARY
505 @cindex LC_MONETARY environment variable
506 This specifies what locale to use for formatting monetary values.
507
508 @item LC_NUMERIC
509 @cindex LC_NUMERIC environment variable
510 This specifies what locale to use for formatting numbers.
511
512 @item LC_TIME
513 @cindex LC_TIME environment variable
514 This specifies what locale to use for formatting date/time values.
515
516 @item _POSIX_OPTION_ORDER
517 @cindex _POSIX_OPTION_ORDER environment variable.
518 If this environment variable is defined, it suppresses the usual
519 reordering of command line arguments by @code{getopt}.  @xref{Program
520 Argument Syntax Conventions}.
521 @end table
522
523 @node Program Termination
524 @section Program Termination
525 @cindex program termination
526 @cindex process termination
527
528 @cindex exit status value
529 The usual way for a program to terminate is simply for its @code{main}
530 function to return.  The @dfn{exit status value} returned from the
531 @code{main} function is used to report information back to the process's
532 parent process or shell.
533
534 A program can also terminate normally calling the @code{exit}
535 function
536
537 In addition, programs can be terminated by signals; this is discussed in
538 more detail in @ref{Signal Handling}.  The @code{abort} function causes
539 a terminal that kills the program.
540
541 @menu
542 * Normal Program Termination::
543 * Aborting a Program::
544 * Process Termination Details::
545 @end menu
546
547 @node Normal Program Termination
548 @subsection Normal Program Termination
549
550 @comment stdlib.h
551 @comment ANSI
552 @deftypefun void exit (int @var{status})
553 The @code{exit} function causes normal program termination with status
554 @var{status}.  This function does not return.
555 @end deftypefun
556
557 When a program terminates normally by returning from its @code{main}
558 function or by calling @code{exit}, the following actions occur in
559 sequence:
560
561 @enumerate
562 @item 
563 Functions that were registered with the @code{atexit} or @code{on_exit}
564 functions are called in the reverse order of their registration.  This
565 mechanism allows your application to specify its own ``cleanup'' actions
566 to be performed at program termination.  Typically, this is used to do
567 things like saving program state information in a file, or unlock locks
568 in shared data bases.
569
570 @item 
571 All open streams are closed; writing out any buffered output data.  See
572 @ref{Opening and Closing Streams}.  In addition, temporary files opened
573 with the @code{tmpfile} function are removed; see @ref{Temporary Files}.
574
575 @item 
576 @code{_exit} is called.  @xref{Termination Internals}
577 @end enumerate
578
579 @node Exit Status
580 @subsection Exit Status
581
582 The most common exit status values are zero, meaning success, and one,
583 usually meaning failure of an unspecified nature.  Some programs use
584 other status values so that they can distinguish various kinds of
585 failure.  And sometimes the value of one is used to mean ``false''
586 rather than a real failure.  For example, comparison programs such as
587 @code{cmp} and @code{diff} return 1 as the status code just to indicate
588 that the files compared were not identical.
589
590 @strong{Portability note:} Some non-POSIX systems use different
591 conventions for exit status values.  For greater portability, you can
592 use the macros @code{EXIT_SUCCESS} and @code{EXIT_FAILURE} for the
593 conventional status value for success and failure, respectively.  They
594 are declared in the file @file{stdlib.h}.
595 @pindex stdlib.h
596
597 @comment stdlib.h
598 @comment ANSI
599 @deftypevr Macro int EXIT_SUCCESS
600 This macro can be used with the @code{exit} function to indicate
601 successful program completion.
602
603 On POSIX systems, the value of this macro is @code{0}.  On other
604 systems, the value might be some other (possibly non-constant) integer
605 expression.
606 @end deftypevr
607
608 @comment stdlib.h
609 @comment ANSI
610 @deftypevr Macro int EXIT_FAILURE
611 This macro can be used with the @code{exit} function to indicate
612 unsuccessful program completion in a general sense.
613
614 On POSIX systems, the value of this macro is @code{1}.  On other
615 systems, the value might be some other (possibly non-constant) integer
616 expression.  Other nonzero status values also indicate future.  Certain
617 programs use different nonzero status values to indicate particular
618 kinds of "non-success".  For example, @code{diff} uses status value
619 @code{1} to mean that the files are different, and @code{2} or more to
620 mean that there was difficulty in opening the files.
621 @end deftypevr
622
623 @node Cleanups on Exit
624 @subsection Cleanups on Exit
625
626 @comment stdlib.h
627 @comment ANSI
628 @deftypefun int atexit (void (*@var{function}))
629 The @code{atexit} function registers the function @var{function} to be
630 called at normal program termination.  The @var{function} is called with
631 no arguments.
632
633 The return value from @code{atexit} is zero on success and nonzero if
634 the function cannot be registered. 
635 @end deftypefun
636
637 @comment stdlib.h
638 @comment GNU
639 @deftypefun int on_exit (void (*@var{function})(int @var{status}, void *@var{arg}), void *@var{arg})
640 This function is a somewhat more powerful variant of @code{atexit}.  It
641 accepts two arguments, a function @var{function} and an arbitrary
642 pointer @var{arg}.  At normal program termination, the @var{function} is
643 called with two arguments:  the @var{status} value passed to @code{exit},
644 and the @var{arg}.
645
646 This function is a GNU extension, and may not be supported by other
647 implementations.
648 @end deftypefun
649
650 Here's a trivial program that illustrates the use of @code{exit} and
651 @code{atexit}:
652
653 @example
654 #include <stdio.h>
655 #include <stdlib.h>
656
657 void bye (void)
658 @{
659   printf ("Goodbye, cruel world....\n");
660 @}
661
662 void main (void)
663 @{
664   atexit (bye);
665   exit (EXIT_SUCCESS);
666 @}
667 @end example
668
669 @noindent
670 When this program is executed, it just prints the message and exits.
671
672
673 @node Aborting a Program
674 @subsection Aborting a Program
675 @cindex aborting a program
676
677 You can abort your program using the @code{abort} function.  The prototype
678 for this function is in @file{stdlib.h}.
679 @pindex stdlib.h
680
681 @comment stdlib.h
682 @comment ANSI
683 @deftypefun void abort ()
684 The @code{abort} function causes abnormal program termination, without
685 executing functions registered with @code{atexit} or @code{on_exit}.
686
687 This function actually terminates the process by raising a
688 @code{SIGABRT} signal, and your program can include a handler to
689 intercept this signal; see @ref{Signal Handling}.
690
691 @strong{Incomplete:}  Why would you want to define such a handler?
692 @end deftypefun
693
694 @node Termination Internals
695 @subsection Termination Internals
696
697 The @code{_exit} function is the primitive used for process termination
698 by @code{exit}.  It is declared in the header file @file{unistd.h}.
699 @pindex unistd.h
700
701 @comment unistd.h
702 @comment POSIX.1
703 @deftypefun void _exit (int @var{status})
704 The @code{_exit} function is the primitive for causing a process to
705 terminate with status @var{status}.  Calling this function does not
706 execute cleanup functions registered with @code{atexit} or
707 @code{on_exit}.
708 @end deftypefun
709
710 When a process terminates for any reason---either by an explicit
711 termination call, or termination as a result of a signal---the
712 following things happen:
713
714 @itemize @bullet
715 @item
716 All open file descriptors in the process are closed.  @xref{Low-Level
717 Input/Output}.
718
719 @item
720 The low-order 8 bits of the return status code are saved to be reported
721 back to the parent process via @code{wait} or @code{waitpid}; see
722 @ref{Process Completion}.
723
724 @item
725 Any child processes of the process being terminated are assigned a new
726 parent process.  (This is the @code{init} process, with process ID 1.)
727
728 @item
729 A @code{SIGCHLD} signal is sent to the parent process.
730
731 @item
732 If the process is a session leader that has a controlling terminal, then
733 a @code{SIGHUP} signal is sent to each process in the foreground job,
734 and the controlling terminal is disassociated from that session.
735 @xref{Job Control}.
736
737 @item
738 If termination of a process causes a process group to become orphaned,
739 and any member of that process group is stopped, then a @code{SIGHUP}
740 signal and a @code{SIGCONT} signal are sent to each process in the
741 group.  @xref{Job Control}.
742 @end itemize
743
744 @node Creating New Processes
745 @section Creating New Processes
746
747 This section describes how your program can cause other programs to be
748 executed.  Actually, there are three distinct operations involved:
749 creating a new child process, causing the new process to execute a
750 program, and coordinating the completion of the child process with the
751 original program.
752
753 The @code{system} function provides a simple, portable mechanism for
754 running another program; it does all three steps automatically.  If you
755 need more control over the details of how this is done, you can use the
756 primitive functions to do each step individually instead.
757
758 @menu
759 * Running a Command::                   The easy way to run another program.
760 * Process Creation Concepts::           An overview of the hard way to do it.
761 * Process Identification::              How to get the process ID of a process.
762 * Creating a Process::                  How to fork a child process.
763 * Executing a File::                    How to get a process to execute another
764                                          program.
765 * Process Completion::                  How to tell when a child process has
766                                          completed.
767 * Process Completion Status::           How to interpret the status value 
768                                          returned from a child process.
769 * BSD Process Completion Functions::    More functions, for backward
770                                          compatibility.
771 * Process Creation Example::            A complete example program.
772 @end menu
773
774
775 @node Running a Command
776 @subsection Running a Command
777 @cindex running a command
778
779 The easy way to run another program is to use the @code{system}
780 function.  This function does all the work of running a subprogram, but
781 it doesn't give you much control over the details: you have to wait
782 until the subprogram terminates before you can do anything else.
783
784 @pindex stdlib.h
785
786 @comment stdlib.h
787 @comment ANSI
788 @deftypefun int system (const char *@var{command})
789 This function executes @var{command} as a shell command.  In the GNU C
790 library, it always uses the default shell @code{sh} to run the command.
791 In particular, it searching the directories in @code{PATH} to find
792 programs to execute.  The return value is @code{-1} if it wasn't
793 possible to create the shell process, and otherwise is the status of the
794 shell process.  @xref{Process Completion}, for details on how this
795 status code can be interpreted.
796 @pindex sh
797 @end deftypefun
798
799 The @code{system} function is declared in the header file
800 @file{stdlib.h}.
801
802 @strong{Portability Note:} Some C implementations may not have any
803 notion of a command processor that can execute other programs.  You can
804 determine whether a command processor exists by executing @code{system
805 (o)}; in this case the return value is nonzero if and only if such a
806 processor is available.
807
808 The @code{popen} and @code{pclose} functions (@pxref{Pipe to a
809 Subprocess}) are closely related to the @code{system} function.  They
810 allow the parent process to communicate with the standard input and
811 output channels of the command being executed.
812
813 @node Process Creation Concepts
814 @subsection Process Creation Concepts
815
816 This section gives an overview of processes and of the steps involved in
817 creating a process and making it run another program.
818
819 @cindex process ID
820 @cindex process lifetime
821 Each process is named by a @dfn{process ID} number.  A unique process ID
822 is allocated to each process when it is created.  The @dfn{lifetime} of
823 a process ends when its termination is reported to its parent process;
824 at that time, all of the process resources, including its process ID,
825 are freed.
826
827 @cindex creating a process
828 @cindex forking a process
829 @cindex child process
830 @cindex parent process
831 Processes are created with the @code{fork} system call (so the operation
832 of creating a new process is sometimes called @dfn{forking} a process).
833 The @dfn{child process} created by @code{fork} is an exact clone of the
834 original @dfn{parent process}, except that it has its own process ID.
835
836 After forking a child process, both the parent and child processes
837 continue to execute normally.  If you want your program to wait for a
838 child process to finish executing before continuing, you must do this
839 explicitly after the fork operation.  This is done with the @code{wait}
840 or @code{waitpid} functions (@pxref{Process Completion}).  These
841 functions give the parent information about why the child
842 terminated---for example, its exit status code.
843
844 A newly forked child process continues to execute the same program as
845 its parent process, at the point where the @code{fork} call returns.
846 You can use the return value from @code{fork} to tell whether the program
847 is running in the parent process or the child.
848
849 @cindex process image
850 Having all processes run the same program is usually not very useful.
851 But the child can execute another program using one of the @code{exec}
852 functions; see @ref{Executing a File}.  The program that the process is
853 executing is called its @dfn{process image}.  Starting execution of a
854 new program causes the process to forget all about its current process
855 image; when the new program exits, the process exits too, instead of
856 returning to the previous process image.
857
858
859 @node Process Identification
860 @subsection Process Identification
861
862 The @code{pid_t} data type represents process IDs.  You can get the
863 process ID of a process by calling @code{getpid}.  The function
864 @code{getppid} returns the process ID of the parent of the parent of the
865 current process (this is also known as the @dfn{parent process ID}).
866 Your program should include the header files @file{unistd.h} and
867 @file{sys/types.h} to use these functions.
868 @pindex sys/types.h
869 @pindex unistd.h
870
871 @comment sys/types.h
872 @comment POSIX.1
873 @deftp {Data Type} pid_t
874 The @code{pid_t} data type is a signed integer type which is capable
875 of representing a process ID.  In the GNU library, this is an @code{int}.
876 @end deftp
877
878 @comment unistd.h
879 @comment POSIX.1
880 @deftypefun pid_t getpid ()
881 The @code{getpid} function returns the process ID of the current process.
882 @end deftypefun
883
884 @comment unistd.h
885 @comment POSIX.1
886 @deftypefun pid_t getppid ()
887 The @code{getppid} function returns the process ID of the parent of the
888 current process.
889 @end deftypefun
890
891 @node Creating a Process
892 @subsection Creating a Process
893
894 The @code{fork} function is the primitive for creating a process.
895 It is declared in the header file @file{unistd.h}.
896 @pindex unistd.h
897
898 @comment unistd.h
899 @comment POSIX.1
900 @deftypefun pid_t fork ()
901 The @code{fork} function creates a new process.
902
903 If the operation is successful, there are then both parent and child
904 processes and both see @code{fork} return, but with different values: it
905 returns a value of @code{0} in the child process and returns the child's
906 process ID in the parent process.  If the child process could not be
907 created, a value of @code{-1} is returned in the parent process.  The
908 following @code{errno} error conditions are defined for this function:
909
910 @table @code
911 @item EAGAIN
912 There aren't enough system resources to create another process, or the
913 user already has too many processes running.
914
915 @item ENOMEM
916 The process requires more space than the system can supply.
917 @end table
918 @end deftypefun
919
920 The specific attributes of the child process that differ from the
921 parent process are:
922
923 @itemize @bullet
924 @item
925 The child process has its own unique process ID.
926
927 @item
928 The parent process ID of the child process is the process ID of its
929 parent process.
930
931 @item
932 The child process gets its own copies of the parent process's open file
933 descriptors.  Subsequently changing attributes of the file descriptors
934 in the parent process won't affect the file descriptors in the child,
935 and vice versa.  @xref{Control Operations}.
936
937 @item
938 The elapsed processor times for the child process are set to zero;
939 see @ref{Processor Time}.
940
941 @item
942 The child doesn't inherit file locks set by the parent process.
943 @xref{Control Operations}.
944
945 @item
946 The child doesn't inherit alarms set by the parent process.
947 @xref{Setting an Alarm}.
948
949 @item
950 The set of pending signals (@pxref{Delivery of Signal}) for the child
951 process is cleared.  (The child process inherits its mask of blocked
952 signals and signal actions from the parent process.)
953 @end itemize 
954
955
956 @comment unistd.h
957 @comment BSD
958 @deftypefun pid_t vfork (void)
959 The @code{vfork} function is similar to @code{fork} but more efficient;
960 however, there are restrictions you must follow to use it safely.
961
962 While @code{fork} makes a complete copy of the calling process's address
963 space and allows both the parent and child to execute independently,
964 @code{vfork} does not make this copy.  Instead, the child process
965 created with @code{vfork} shares its parent's address space until it calls
966 one of the @code{exec} functions.  In the meantime, the parent process
967 suspends execution.
968
969 You must be very careful not to allow the child process created with
970 @code{vfork} to modify any global data or even local variables shared
971 with the parent.  Furthermore, the child process cannot return from (or
972 do a long jump out of) the function that called @code{vfork}!  This
973 would leave the parent process's control information very confused.  If
974 in doubt, use @code{fork} instead.
975
976 Some operating systems don't really implement @code{vfork}.  The GNU C
977 library permits you to use @code{vfork} on all systems, but actually
978 executes @code{fork} if @code{vfork} isn't available.
979 @end deftypefun
980
981 @node Executing a File
982 @subsection Executing a File
983 @cindex executing a file
984 @cindex @code{exec} functions
985
986 This section describes the @code{exec} family of functions, for executing
987 a file as a process image.  You can use these functions to make a child
988 process execute a new program after it has been forked.
989
990 The functions in this family differ in how you specify the arguments,
991 but otherwise they all do the same thing.  They are declared in the
992 header file @file{unistd.h}.
993 @pindex unistd.h
994
995 @comment unistd.h
996 @comment POSIX.1
997 @deftypefun int execv (const char *@var{filename}, char *const @var{argv}@t{[]})
998 The @code{execv} function executes the file named by @var{filename} as a
999 new process image.
1000
1001 The @var{argv} argument is an array of null-terminated strings that is
1002 used to provide a value for the @code{argv} argument to the @code{main}
1003 function of the program to be executed.  The last element of this array
1004 must be a null pointer.  @xref{Program Arguments}, for information on
1005 how programs can access these arguments.
1006
1007 The environment for the new process image is taken from the
1008 @code{environ} variable of the current process image; see @ref{Environment
1009 Variables}, for information about environments.
1010 @end deftypefun
1011
1012 @comment unistd.h
1013 @comment POSIX.1
1014 @deftypefun int execl (const char *@var{filename}, const char *@var{arg0}, @dots{})
1015 This is similar to @code{execv}, but the @var{argv} strings are
1016 specified individually instead of as an array.  A null pointer must be
1017 passed as the last such argument.
1018 @end deftypefun
1019
1020 @comment unistd.h
1021 @comment POSIX.1
1022 @deftypefun int execve (const char *@var{filename}, char *const @var{argv}@t{[]}, char *const @var{env}@t{[]})
1023 This is similar to @code{execv}, but permits you to specify the environment
1024 for the new program explicitly as the @var{env} argument.  This should
1025 be an array of strings in the same format as for the @code{environ} 
1026 variable; see @ref{Environment Access}.
1027 @end deftypefun
1028
1029 @comment unistd.h
1030 @comment POSIX.1
1031 @deftypefun int execle (const char *@var{filename}, const char *@var{arg0}, char *const @var{env}@t{[]}, @dots{})
1032 This is similar to @code{execl}, but permits you to specify the
1033 environment for the new program explicitly.  The environment argument is
1034 passed following the null pointer that marks the last @var{argv}
1035 argument, and should be an array of strings in the same format as for
1036 the @code{environ} variable.
1037 @end deftypefun
1038
1039 @comment unistd.h
1040 @comment POSIX.1
1041 @deftypefun int execvp (const char *@var{filename}, char *const @var{argv}@t{[]})
1042 The @code{execvp} function is similar to @code{execv}, except that it
1043 searches the directories listed in the @code{PATH} environment variable
1044 (@pxref{Standard Environment Variables}) to find the full file name of a
1045 file from @var{filename} if @var{filename} does not contain a slash.
1046
1047 This function is useful for executing installed system utility programs,
1048 so that the user can control where to look for them.  It is also useful
1049 in shells, for executing commands typed by the user.
1050 @end deftypefun
1051
1052 @comment unistd.h
1053 @comment POSIX.1
1054 @deftypefun int execlp (const char *@var{filename}, const char *@var{arg0}, @dots{})
1055 This function is like @code{execl}, except that it performs the same
1056 file name searching as the @code{execvp} function.
1057 @end deftypefun
1058
1059
1060 The size of the argument list and environment list taken together must not
1061 be greater than @code{ARG_MAX} bytes.  @xref{System Parameters}.
1062
1063 @strong{Incomplete:}  The POSIX.1 standard requires some statement here
1064 about how null terminators, null pointers, and alignment requirements
1065 affect the total size of the argument and environment lists.
1066
1067 These functions normally don't return, since execution of a new program
1068 causes the currently executing program to go away completely.  A value
1069 of @code{-1} is returned in the event of a failure.  In addition to the
1070 usual file name syntax errors (@pxref{File Name Errors}), the following
1071 @code{errno} error conditions are defined for these functions:
1072
1073 @table @code
1074 @item E2BIG
1075 The combined size of the new program's argument list and environment list
1076 is larger than @code{ARG_MAX} bytes.
1077
1078 @item ENOEXEC
1079 The specified file can't be executed because it isn't in the right format.
1080
1081 @item ENOMEM
1082 Executing the specified file requires more storage than is available.
1083 @end table
1084
1085 If execution of the new file is successful, the access time field of the
1086 file is updated as if the file had been opened.  @xref{File Times}, for
1087 more details about access times of files.
1088
1089 The point at which the file is closed again is not specified, but
1090 is at some point before the process exits or before another process
1091 image is executed.
1092
1093 Executing a new process image completely changes the contents of memory,
1094 except for the arguments and the environment, but many other attributes
1095 of the process are unchanged:
1096
1097 @itemize @bullet
1098 @item
1099 The process ID and the parent process ID.  @xref{Process Creation Concepts}.
1100
1101 @item
1102 Session and process group membership.  @xref{Job Control Concepts}.
1103
1104 @item
1105 Real user ID and group ID, and supplementary group IDs.  @xref{User/Group
1106 IDs of a Process}.
1107
1108 @item
1109 Pending alarms.  @xref{Setting an Alarm}.
1110
1111 @item
1112 Current working directory and root directory.  @xref{Working Directory}.
1113
1114 @item
1115 File mode creation mask.  @xref{Setting Permissions}.
1116
1117 @item
1118 Process signal mask; see @ref{Process Signal Mask}.
1119
1120 @item
1121 Pending signals; see @ref{Blocking Signals}.
1122
1123 @item
1124 Elapsed processor time associated with the process; see @ref{Processor Time}.
1125 @end itemize
1126
1127 If the set-user-ID and set-group-ID mode bits of the process image file
1128 are set, this affects the effective user ID and effective group ID
1129 (respectively) of the process.  These concepts are discussed in detail
1130 in @ref{User/Group IDs of a Process}.
1131
1132 Signals that are set to be ignored in the existing process image are
1133 also set to be ignored in the new process image.  All other signals are
1134 set to the default action in the new process image.  For more
1135 information about signals, see @ref{Signal Handling}.
1136
1137 File descriptors open in the existing process image remain open in the
1138 new process image, unless they have the @code{FD_CLOEXEC}
1139 (close-on-exec) flag set.  The files that remain open inherit all
1140 attributes of the open file description from the existing process image,
1141 including file locks.  File descriptors are discussed in @ref{Low-Level
1142 Input/Output}.
1143
1144 Streams, by contrast, cannot survive through @code{exec} functions,
1145 because they are located in the memory of the process itself.  The new
1146 process image has no streams except those it creates afresh.  Each of
1147 the streams in the pre-@code{exec} process image has a descriptor inside
1148 it, and these descriptors do survive through @code{exec} (provided that
1149 they do not have @code{FD_CLOEXEC} set.  The new process image can
1150 reconnect these to new streams using @code{fdopen}.
1151
1152 @node Process Completion
1153 @subsection Process Completion
1154 @cindex process completion
1155 @cindex waiting for completion of child process
1156 @cindex testing exit status of child process
1157
1158 The functions described in this section are used to wait for a child
1159 process to terminate or stop, and determine its status.  These functions
1160 are declared in the header file @file{sys/wait.h}.
1161 @pindex sys/wait.h
1162
1163 @comment sys/wait.h
1164 @comment POSIX.1
1165 @deftypefun pid_t waitpid (pid_t @var{pid}, int *@var{status_ptr}, int @var{options})
1166 The @code{waitpid} function is used to request status information from a
1167 child process whose process ID is @var{pid}.  Normally, the calling
1168 process is suspended until the child process makes status information
1169 available by terminating.
1170
1171 Other values for the @var{pid} argument have special interpretations.  A
1172 value of @code{-1} or @code{WAIT_ANY} requests status information for
1173 any child process; a value of @code{0} or @code{WAIT_MYPGRP} requests
1174 information for any child process in the same process group as the
1175 calling process; and any other negative value @minus{} @var{pgid}
1176 requests information for any child process whose process group ID is
1177 @var{pgid}.
1178
1179 If status information for a child process is available immediately, this
1180 function returns immediately without waiting.  If more than one eligible
1181 child process has status information available, one of them is chosen
1182 randomly, and its status is returned immediately.  To get the status
1183 from the other programs, you need to call @code{waitpid} again.
1184
1185 The @var{options} argument is a bit mask.  Its value should be the
1186 bitwise OR (that is, the @samp{|} operator) of zero or more of the
1187 @code{WNOHANG} and @code{WUNTRACED} flags.  You can use the
1188 @code{WNOHANG} flag to indicate that the parent process shouldn't wait;
1189 and the @code{WUNTRACED} flag to request status information from stopped
1190 processes as well as processes that have terminated.
1191
1192 The status information from the child process is stored in the object
1193 that @var{status_ptr} points to, unless @var{status_ptr} is a null pointer.
1194
1195 The return value is normally the process ID of the child process whose
1196 status is reported.  If the @code{WNOHANG} option was specified and no
1197 child process is waiting to be noticed, a value of zero is returned.  A
1198 value of @code{-1} is returned in case of error.  The following
1199 @code{errno} error conditions are defined for this function:
1200
1201 @table @code
1202 @item EINTR
1203 The function was interrupted by delivery of a signal to the calling
1204 process.
1205
1206 @item ECHILD
1207 There are no child processes to wait for, or the specified @var{pid}
1208 is not a child of the calling process.
1209
1210 @item EINVAL
1211 An invalid value was provided for the @var{options} argument.
1212 @end table
1213 @end deftypefun
1214
1215 These symbolic constants are defined as values for the @var{pid} argument
1216 to the @code{waitpid} function.
1217
1218 @table @code
1219 @item WAIT_ANY
1220 This constant macro (whose value is @code{-1}) specifies that
1221 @code{waitpid} should return status information about any child process.
1222
1223 @item WAIT_MYPGRP
1224 This constant (with value @code{0}) specifies that @code{waitpid} should
1225 return status information about any child process in the same process
1226 group as the calling process.
1227
1228 These symbolic constants are defined as flags for the @var{options}
1229 argument to the @code{waitpid} function.  You can bitwise-OR the flags
1230 together to obtain a value to use as the argument.
1231
1232 @item WNOHANG
1233 This flag specifies that @code{waitpid} should return immediately
1234 instead of waiting if there is no child process ready to be noticed.
1235
1236 @item WUNTRACED
1237 This macro is used to specify that @code{waitpid} should also report the
1238 status of any child processes that have been stopped as well as those
1239 that have terminated.
1240 @end table
1241
1242 @deftypefun pid_t wait (int *@var{status_ptr})
1243 This is a simplified version of @code{waitpid}, and is used to wait
1244 until any one child process terminates.
1245
1246 @example
1247 wait (&status)
1248 @end example
1249
1250 @noindent
1251 is equivalent to:
1252
1253 @example
1254 waitpid (-1, &status, 0)
1255 @end example
1256
1257 Here's an example of how to use @code{waitpid} to get the status from
1258 all child processes that have terminated, without ever waiting.  This
1259 function is designed to be used as a handler for @code{SIGCHLD}, the
1260 signal that indicates that at least one child process has terminated.
1261
1262 @example
1263 void
1264 sigchld_handler (int signum)
1265 @{
1266   int pid;
1267   int status;
1268   while (1) @{
1269     pid = waitpid (WAIT_ANY, Estatus, WNOHANG);
1270     if (pid < 0) @{
1271       perror ("waitpid");
1272       break;
1273     @}
1274     if (pid == 0)
1275       break;
1276     notice_termination (pid, status);
1277   @}
1278 @}
1279 @end example
1280 @end deftypefun
1281
1282 @node Process Completion Status
1283 @subsection Process Completion Status
1284
1285 If the exit status value (@pxref{Program Termination}) of the child
1286 process is zero, then the status value reported by @code{waitpid} or
1287 @code{wait} is also zero.  You can test for other kinds of information
1288 encoded in the returned status value using the following macros.
1289 These macros are defined in the header file @file{sys/wait.h}.
1290 @pindex sys/wait.h
1291
1292 @comment sys/wait.h
1293 @comment POSIX.1
1294 @deftypefn Macro int WIFEXITED (int @var{status})
1295 This macro returns a non-zero value if the child process terminated
1296 normally with @code{exit} or @code{_exit}.
1297 @end deftypefn
1298
1299 @comment sys/wait.h
1300 @comment POSIX.1
1301 @deftypefn Macro int WEXITSTATUS (int @var{status})
1302 If @code{WIFEXITED} is true of @var{status}, this macro returns the
1303 low-order 8 bits of the exit status value from the child process.
1304 @end deftypefn
1305
1306 @comment sys/wait.h
1307 @comment POSIX.1
1308 @deftypefn Macro int WIFSIGNALED (int @var{status})
1309 This macro returns a non-zero value if the child process terminated
1310 by receiving a signal that was not handled.
1311 @end deftypefn
1312
1313 @comment sys/wait.h
1314 @comment POSIX.1
1315 @deftypefn Macro int WTERMSIG (int @var{status})
1316 If @code{WIFSIGNALED} is true of @var{status}, this macro returns the
1317 number of the signal that terminated the child process.
1318 @end deftypefn
1319
1320 @comment sys/wait.h
1321 @comment BSD
1322 @deftypefn Macro int WCOREDUMP (int @var{status})
1323 This macro returns a non-zero value if the child process terminated
1324 and produced a core dump.
1325 @end deftypefn
1326
1327 @comment sys/wait.h
1328 @comment POSIX.1
1329 @deftypefn Macro int WIFSTOPPED (int @var{status})
1330 This macro returns a non-zero value if the child process is stopped.
1331 @end deftypefn
1332
1333 @comment sys/wait.h
1334 @comment POSIX.1
1335 @deftypefn Macro int WSTOPSIG (int @var{status})
1336 If @code{WIFSTOPPED} is true of @var{status}, this macro returns the
1337 number of the signal that caused the child process to stop.
1338 @end deftypefn
1339
1340
1341 @node BSD Process Completion Functions
1342 @subsection BSD Process Completion Functions
1343
1344 The GNU library also provides these related facilities for compatibility
1345 with BSD Unix.  BSD uses the @code{union wait} data type to represent
1346 status values rather than an @code{int}.  The two representations are
1347 actually interchangeable; they describe the same bit patterns. The macros
1348 such as @code{WEXITSTATUS} are defined so that they will work on either
1349 kind of object, and the @code{wait} function is defined to accept either
1350 type of pointer as its @var{status_ptr} argument.
1351
1352 These functions are declared in @file{sys/wait.h}.
1353 @pindex sys/wait.h
1354
1355 @comment sys/wait.h
1356 @comment BSD
1357 @deftp {union Type} wait
1358 This data type represents program termination status values.  It has
1359 the following members:
1360
1361 @table @code
1362 @item int w_termsig
1363 This member is equivalent to the @code{WTERMSIG} macro.
1364
1365 @item int w_coredump
1366 This member is equivalent to the @code{WCOREDUMP} macro.
1367
1368 @item int w_retcode
1369 This member is equivalent to the @code{WEXISTATUS} macro.
1370
1371 @item int w_stopsig
1372 This member is equivalent to the @code{WSTOPSIG} macro.
1373 @end table
1374
1375 Instead of accessing these members directly, you should use the
1376 equivalent macros.
1377 @end deftp
1378
1379 @comment sys/wait.h
1380 @comment BSD
1381 @deftypefun pid_t wait3 (union wait *@var{status_ptr}, int @var{options}, void * @var{usage})
1382 If @var{usage} is a null pointer, this function is equivalent to
1383 @code{waitpid (-1, @var{status_ptr}, @var{options})}.
1384
1385 The @var{usage} argument may also be a pointer to a 
1386 @code{struct rusage} object.  Information about system resources used by
1387 terminated processes (but not stopped processes) is returned in this
1388 structure.
1389
1390 @strong{Incomplete:}  The description of the @code{struct rusage} structure
1391 hasn't been written yet.  Put in a cross-reference here.
1392 @end deftypefun
1393
1394 @comment sys/wait.h
1395 @comment BSD
1396 @deftypefun pid_t wait4 (pid_t @var{pid}, union wait *@var{status_ptr}, int @var{options}, void *@var{usage})
1397 If @var{usage} is a null pointer, this function is equivalent to
1398 @code{waitpid (@var{pid}, @var{status_ptr}, @var{options})}.
1399
1400 The @var{usage} argument may also be a pointer to a 
1401 @code{struct rusage} object.  Information about system resources used by
1402 terminated processes (but not stopped processes) is returned in this
1403 structure.
1404
1405 @strong{Incomplete:}  The description of the @code{struct rusage} structure
1406 hasn't been written yet.  Put in a cross-reference here.
1407 @end deftypefun
1408
1409 @node Process Creation Example
1410 @subsection Process Creation Example
1411
1412 Here is an example program showing how you might write a function
1413 similar to the built-in @code{system}.  It executes its @var{command}
1414 argument using the equivalent of @samp{sh -c @var{command}}.
1415
1416 @example
1417 #include <stddef.h>
1418 #include <stdlib.h>
1419 #include <unistd.h>
1420 #include <sys/types.h>
1421 #include <sys/wait.h>
1422
1423 /* @r{Execute the command using this shell program.}  */
1424 #define SHELL "/bin/sh"
1425
1426 int 
1427 my_system (char *command)
1428 @{
1429   int status;
1430   pid_t pid;
1431
1432   pid =  fork ();
1433   if (pid == 0) @{
1434     /* @r{This is the child process.  Execute the shell command.} */
1435     execl (SHELL, SHELL, "-c", command, NULL);
1436     exit (EXIT_FAILURE);
1437   @}
1438   else if (pid < 0)
1439     /* @r{The fork failed.  Report failure.}  */
1440     status = -1;
1441   else @{
1442     /* @r{This is the parent process.  Wait for the child to complete.}  */
1443     if (waitpid (pid, &status, 0) != pid)
1444       status = -1;
1445   @}
1446   return status;
1447 @}
1448 @end example
1449
1450 @comment Yes, this example has been tested.
1451
1452 There are a couple of things you should pay attention to in this
1453 example.
1454
1455 Remember that the first @code{argv} argument supplied to the program
1456 represents the name of the program being executed.  That is why, in the
1457 call to @code{execl}, @code{SHELL} is supplied once to name the program
1458 to execute and a second time to supply a value for @code{argv[0]}.  
1459
1460 The @code{execl} call in the child process doesn't return if it is
1461 successful.  If it fails, you must do something to make the child
1462 process terminate.  Just returning a bad status code with @code{return}
1463 would leave two processes running the original program.  Instead, the
1464 right behavior is for the child process to report failure to its parent
1465 process.  To do this, @code{exit} is called with a failure status.