Misc edits.
[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 * User/Group IDs of a Process:: Controlling what privileges your program has.
28 @end menu
29
30
31 @node Program Arguments
32 @section Program Arguments
33 @cindex program arguments
34 @cindex command line arguments
35
36 @cindex @code{main} function
37 When your C program starts, it begins by executing the function called
38 @code{main}.  You can define @code{main} either to take no arguments,
39 or to take two arguments that represent the command line arguments
40 to the program, like this:
41
42 @example
43 int main (int @var{argc}, char *@var{argv}[])
44 @end example
45
46 @cindex argc (program argument count)
47 @cindex argv (program argument vector)
48 The command line arguments are the whitespace-separated tokens typed by
49 the user to the shell in invoking the program.  The value of the
50 @var{argc} argument is the number of command line arguments.  The
51 @var{argv} argument is a vector of pointers to @code{char}; sometimes it
52 is also declared as @samp{char **@var{argv}}.  The elements of
53 @var{argv} are the individual command line argument strings.  By
54 convention, @samp{@var{argv}[0]} is the file name of the program being
55 run, and @samp{@var{argv}[@var{argc}]} is a null pointer.
56
57 If the syntax for the command line arguments to your program is simple
58 enough, you can simply pick the arguments off from @var{argv} by hand.
59 But unless your program takes a fixed number of arguments, or all of the
60 arguments are interpreted in the same way (as file names, for example),
61 you are usually better off using @code{getopt} to do the parsing.
62
63 @menu
64 * Program Argument Syntax Conventions::         By convention, program
65                                                  options are specified by a
66                                                  leading hyphen.
67 * Parsing Program Arguments::                   The @code{getopt} function.
68 * Example of Parsing Program Arguments::        An example of @code{getopt}.
69 @end menu
70
71 @node Program Argument Syntax Conventions
72 @subsection Program Argument Syntax Conventions
73 @cindex program argument syntax
74 @cindex syntax, for program arguments
75 @cindex command argument syntax
76
77 The @code{getopt} function decodes options following the usual
78 conventions for POSIX utilities:
79
80 @itemize @bullet
81 @item
82 Arguments are options if they begin with a hyphen delimiter (@samp{-}).
83
84 @item
85 Multiple options may follow a hyphen delimiter in a single token if
86 the options do not take arguments.  Thus, @samp{-abc} is equivalent to
87 @samp{-a -b -c}.
88
89 @item
90 Option names are single alphanumeric (as for @code{isalnum};
91 see @ref{Classification of Characters}).
92
93 @item
94 Certain options require an argument.  For example, the @samp{-o} 
95 command of the ld command requires an argument---an output file name.
96
97 @item
98 An option and its argument may or may appear as separate tokens.  (In
99 other words, the whitespace separating them is optional.)  Thus,
100 @samp{-o foo} and @samp{-ofoo} are equivalent.
101
102 @item
103 Options typically precede other non-option arguments.
104
105 The implementation of @code{getopt} in the GNU C library normally makes
106 it appear as if all the option arguments were specified before all the
107 non-option arguments for the purposes of parsing, even if the user of
108 your program intermixed option and non-option arguments.  It does this
109 by reordering the elements of the @var{argv} array.  This behavior is
110 nonstandard; if you want to suppress it, define the
111 @code{_POSIX_OPTION_ORDER} environment variable.  @xref{Standard
112 Environment Variables}.
113
114 @item
115 The argument @samp{--} terminates all options; any following arguments
116 are treated as non-option arguments, even if they begin with a hyphen.
117
118 @item
119 A token consisting of a single hyphen character is interpreted as an
120 ordinary non-option argument.  By convention, it is used to specify
121 input from or output to the standard input and output streams.
122
123 @item
124 Options may be supplied in any order, or appear multiple times.  The
125 interpretation is left up to the particular application program.
126 @end itemize
127
128 @node Parsing Program Arguments
129 @subsection Parsing Program Arguments
130 @cindex program arguments, parsing
131 @cindex command arguments, parsing
132 @cindex parsing program arguments
133
134 Here are the details about how to call the @code{getopt} function.  To
135 use this facility, your program must include the header file
136 @file{unistd.h}.
137 @pindex unistd.h
138
139 @comment unistd.h
140 @comment POSIX.2
141 @deftypevar int opterr
142 If the value of this variable is nonzero, then @code{getopt} prints an
143 error message to the standard error stream if it encounters an unknown
144 option character or an option with a missing required argument.  This is
145 the default behavior.  If you set this variable to zero, @code{getopt}
146 does not print any messages, but it still returns @code{?} to indicate
147 an error.
148 @end deftypevar
149
150 @comment unistd.h
151 @comment POSIX.2
152 @deftypevar int optopt
153 When @code{getopt} encounters an unknown option character or an option
154 with a missing required argument, it stores that option character in
155 this variable.  You can use this for providing your own diagnostic
156 messages.
157 @end deftypevar
158
159 @comment unistd.h
160 @comment POSIX.2
161 @deftypevar int optind
162 This variable is set by @code{getopt} to the index of the next element
163 of the @var{argv} array to be processed.  Once @code{getopt} has found
164 all of the option arguments, you can use this variable to determine
165 where the remaining non-option arguments begin.  The initial value of
166 this variable is @code{1}.
167 @end deftypevar
168
169 @comment unistd.h
170 @comment POSIX.2
171 @deftypevar {char *} optarg
172 This variable is set by @code{getopt} to point at the value of the
173 option argument, for those options that accept arguments.
174 @end deftypevar
175
176 @comment unistd.h
177 @comment POSIX.2
178 @deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options})
179 The @code{getopt} function gets the next option argument from the
180 argument list specified by the @var{argv} and @var{argc} arguments.
181 Normally these arguments' values come directly from the arguments of
182 @code{main}.
183
184 The @var{options} argument is a string that specifies the option
185 characters that are valid for this program.  An option character in this
186 string can be followed by a colon (@samp{:}) to indicate that it takes a
187 required argument.
188
189 If the @var{options} argument string begins with a hyphen (@samp{-}), this
190 is treated specially.  It permits arguments without an option to be
191 returned as if they were associated with option character @samp{\0}.
192
193 The @code{getopt} function returns the option character for the next
194 command line option.  When no more option arguments are available, it
195 returns @code{-1}.  There may still be more non-option arguments; you
196 must compare the external variable @code{optind} against the @var{argv}
197 parameter to check this.
198
199 If the options has an argument, @code{getopt} returns the argument by
200 storing it in the varables @var{optarg}.  You don't ordinarily need to
201 copy the @code{optarg} string, since it is a pointer into the original
202 @var{argv} array, not into a static area that might be overwritten.
203
204 If @code{getopt} finds an option character in @var{argv} that was not
205 included in @var{options}, or a missing option argument, it returns
206 @samp{?} and sets the external variable @code{optopt} to the actual
207 option character.  In addition, if the external variable @code{opterr}
208 is nonzero, @code{getopt} prints an error message.
209 @end deftypefun
210
211 @node Example of Parsing Program Arguments
212 @subsection Example of Parsing Program Arguments
213
214 Here is an example showing how @code{getopt} is typically used.  The
215 key points to notice are:
216
217 @itemize @bullet
218 @item
219 Normally, @code{getopt} is called in a loop.  When @code{getopt} returns
220 @code{-1}, indicating no more options are present, the loop terminates.
221
222 @item
223 A @code{switch} statement is used to dispatch on the return value from
224 @code{getopt}.  In typical use, each case just sets a variable that
225 is used later in the program.
226
227 @item
228 A second loop is used to process the remaining non-option arguments.
229 @end itemize
230
231 @example
232 #include <unistd.h>
233 #include <stdio.h>
234
235 int
236 main (int argc, char **argv)
237 @{
238   int aflag = 0;
239   int bflag = 0;
240   char *cvalue = NULL;
241   int index;
242   int c;
243   opterr = 0;
244
245   while ((c = getopt (argc, argv, "abc:")) >= 0)
246     switch (c) @{
247     case 'a':
248       aflag = 1;
249       break;
250     case 'b':
251       bflag = 1;
252       break;
253     case 'c':
254       cvalue = optarg;
255       break;
256     case '?':
257       if (isprint (optopt))
258         fprintf (stderr, "Unknown option %c.\n", optopt);
259       else
260         fprintf (stderr, "Unknown option character `\\x%x'", optopt);
261       return -1;
262     default:
263       abort ();
264       return -1;
265     @}
266
267   printf ("aflag = %d, bflag = %d, cvalue = %s\n", aflag, bflag, cvalue);
268
269   for (index = optind; index < argc; index++)
270     printf ("Non-option argument %s\n", argv[index]);
271   return 0;
272 @}
273 @end example
274
275 Here are some examples showing what this program prints with different
276 combinations of arguments:
277
278 @example
279 % testopt
280 aflag = 0, bflag = 0, cvalue = (null)
281
282 % testopt -a -b
283 aflag = 1, bflag = 1, cvalue = (null)
284
285 % testopt -ab
286 aflag = 1, bflag = 1, cvalue = (null)
287
288 % testopt -c foo
289 aflag = 0, bflag = 0, cvalue = foo
290
291 % testopt -cfoo
292 aflag = 0, bflag = 0, cvalue = foo
293
294 % testopt arg1
295 aflag = 0, bflag = 0, cvalue = (null)
296 Non-option argument arg1
297
298 % testopt -a arg1
299 aflag = 1, bflag = 0, cvalue = (null)
300 Non-option argument arg1
301
302 % testopt -c foo arg1
303 aflag = 0, bflag = 0, cvalue = foo
304 Non-option argument arg1
305
306 % testopt -a -- -b
307 aflag = 1, bflag = 0, cvalue = (null)
308 Non-option argument -b
309
310 % testopt -a -
311 aflag = 1, bflag = 0, cvalue = (null)
312 Non-option argument -
313 @end example
314
315 @node Environment Variables
316 @section Environment Variables
317
318 @cindex environment variable
319 When a program is executed, it receives information about the context in
320 which it was invoked in two ways.  The first mechanism uses the
321 @var{argv} and @var{argc} arguments to its @code{main} function, and is
322 discussed in @ref{Program Arguments}.  The second mechanism is
323 uses @dfn{environment variables} and is discussed in this section.
324
325 The @var{argv} mechanism is typically used to pass command-line
326 arguments specific to the particular program being invoked.  The
327 environment, on the other hand, keeps track of information that is
328 shared by many programs, changes infrequently, and that is less
329 frequently accessed.
330
331 The environment variables discussed in this section are the same
332 environment variables that you set using the assignments and the
333 @code{export} command in the shell.  Programs executed from the shell
334 inherit all of the environment variables from the shell.
335 @pindex getenv
336
337 @cindex environment
338 Standard environment variables are used for information about the user's
339 home directory, terminal type, current locale, and so on; you can define
340 additional variables for other purposes.  The set of all environment
341 variables that have values is collectively known as the
342 @dfn{environment}.
343
344 Names of environment variables are case-sensitive and must not contain
345 the character @samp{=}.  System-defined environment variables are
346 invariably uppercase.
347
348 The values of environment variables can be anything that can be
349 represented as a string.  A value must not contain an embedded null
350 character, since this is assumed to terminate the string.
351
352
353 @menu
354 * Environment Access::                  How to get and set the values of
355                                          environment variables.
356 * Standard Environment Variables::      These environment variables have
357                                          standard interpretations.
358 @end menu
359
360 @node Environment Access
361 @subsection Environment Access
362 @cindex environment access
363 @cindex environment representation
364
365 The value of an environment variable can be accessed with the
366 @code{getenv} function.  This is declared in the header file
367 @file{stdlib.h}.
368 @pindex stdlib.h
369
370 @comment stdlib.h
371 @comment ANSI
372 @deftypefun {char *} getenv (const char *@var{name})
373 This function returns a string that is the value of the environment
374 variable @var{name}.  You must not modify this string.  In some systems
375 not using the GNU library, it might be overwritten by subsequent calls
376 to @code{getenv} (but not by any other library function).  If the
377 environment variable @var{name} is not defined, the value is a null
378 pointer.
379 @end deftypefun
380
381
382 @comment stdlib.h
383 @comment SVID
384 @deftypefun int putenv (const char *@var{string})
385 The @code{putenv} function adds or removes definitions from the environment.
386 If the @var{string} is of the form @samp{@var{name}=@var{value}}, the
387 definition is added to the environment.  Otherwise, the @var{string} is
388 interpreted as the name of an environment variable, and any definition
389 for this variable in the environment is removed.
390
391 The GNU library provides this function for compatibility with SVID; it
392 may not be available in other systems.
393 @end deftypefun
394
395 You can deal directly with the underlying representation of environment
396 objects to add more variables to the environment (for example, to
397 communicate with another program you are about to execute; see
398 @ref{Executing a File}).  
399
400 @comment unistd.h
401 @comment POSIX.1
402 @deftypevar {char **} environ
403 The environment is represented as an array of strings.  Each string is
404 of the format @samp{@var{name}=@var{value}}.  The order in which
405 strings appear in the environment is not significant, but the same
406 @var{name} must not appear more than once.  The last element of the
407 array is a null pointer.
408
409 This variable is not declared in any header file, but if you declare it
410 in your own program as @code{extern}, the right thing will happen.
411
412 If you just want to get the value of an environment variable, use
413 @code{getenv}.
414 @end deftypevar
415
416 @node Standard Environment Variables
417 @subsection Standard Environment Variables
418 @cindex standard environment variables
419
420 These environment variables have standard meanings.
421 This doesn't mean that they are always present in the
422 environment, though; it just means that if these variables @emph{are}
423 present, they have these meanings, and that you shouldn't try to use
424 these environment variable names for some other purpose.
425
426 @table @code
427 @item HOME
428 @cindex HOME environment variable
429 @cindex home directory
430 This is a string representing the user's @dfn{home directory}, or
431 initial default working directory.  @xref{User Database}, for a
432 more secure way of determining this information.
433
434 @comment RMS says to explay why HOME is better, but I don't know why.
435
436 @item LOGNAME
437 @cindex LOGNAME environment variable
438 This is the name that the user used to log in.  Since the value in the
439 environment can be tweaked arbitrarily, this is not a reliable way to
440 identify the user who is running a process; a function like
441 @code{getlogin} (@pxref{User Identification Functions}) is better for
442 that purpose.
443
444 @comment RMS says to explay why LOGNAME is better, but I don't know why.
445
446 @item PATH
447 @cindex PATH environment variable
448 A @dfn{path} is a sequence of directory names which is used for
449 searching for a file.  The variable @var{PATH} holds a path The
450 @code{execlp} and @code{execvp} functions (@pxref{Executing a File})
451 uses this environment variable, as do many shells and other utilities
452 which are implemented in terms of those functions.
453
454 The syntax of a path is a sequence of directory names separated by
455 colons.  An empty string instead of a directory name stands for the 
456 current directory.  (@xref{Working Directory}.)
457
458 A typical value for this environment variable might be a string like:
459
460 @example
461 .:/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local:/usr/local/bin
462 @end example
463
464 This means that if the user tries to execute a program named @code{foo},
465 the system will look for files named @file{./foo}, @file{/bin/foo},
466 @file{/etc/foo}, and so on.  The first of these files that exists is
467 the one that is executed.
468
469 @item TERM
470 @cindex TERM environment variable
471 This specifies the kind of terminal that is receiving program output.
472 Some programs can make use of this information to take advantage of
473 special escape sequences or terminal modes supported by particular kinds
474 of terminals.  Many programs which use the termcap library
475 (@pxref{Finding a Terminal Description,Find,,termcap,The Termcap Library
476 Manual}) use the @code{TERM} environment variable, for example.
477
478 @item TZ
479 @cindex TZ environment variable
480 This specifies the time zone.  @xref{Time Zone}, for information about
481 the format of this string and how it is used.
482
483 @item LANG
484 @cindex LANG environment variable
485 This specifies the default locale to use for attribute categories where
486 neither @code{LC_ALL} nor the specific environment variable for that
487 category is set.  @xref{Locales}, for more information about
488 locales.
489
490 @item LC_ALL
491 @cindex LC_ALL environment variable
492 This is similar to the @code{LANG} environment variable.  However, its
493 value takes precedence over any values provided for the individual
494 attribute category environment variables, or for the @code{LANG}
495 environment variable.
496
497 @item LC_COLLATE
498 @cindex LC_COLLATE environment variable
499 This specifies what locale to use for string sorting.
500
501 @item LC_CTYPE
502 @cindex LC_CTYPE environment variable
503 This specifies what locale to use for character sets and character
504 classification.
505
506 @item LC_MONETARY
507 @cindex LC_MONETARY environment variable
508 This specifies what locale to use for formatting monetary values.
509
510 @item LC_NUMERIC
511 @cindex LC_NUMERIC environment variable
512 This specifies what locale to use for formatting numbers.
513
514 @item LC_TIME
515 @cindex LC_TIME environment variable
516 This specifies what locale to use for formatting date/time values.
517
518 @item _POSIX_OPTION_ORDER
519 @cindex _POSIX_OPTION_ORDER environment variable.
520 If this environment variable is defined, it suppresses the usual
521 reordering of command line arguments by @code{getopt}.  @xref{Program
522 Argument Syntax Conventions}.
523 @end table
524
525 @node Program Termination
526 @section Program Termination
527 @cindex program termination
528 @cindex process termination
529
530 @cindex exit status value
531 The usual way for a program to terminate is simply for its @code{main}
532 function to return.  The @dfn{exit status value} returned from the
533 @code{main} function is used to report information back to the process's
534 parent process or shell.
535
536 A program can also terminate normally calling the @code{exit}
537 function
538
539 In addition, programs can be terminated by signals; this is discussed in
540 more detail in @ref{Signal Handling}.  The @code{abort} function causes
541 a terminal that kills the program.
542
543 @menu
544 * Normal Program Termination::
545 * Aborting a Program::
546 * Process Termination Details::
547 @end menu
548
549 @node Normal Program Termination
550 @subsection Normal Program Termination
551
552 @comment stdlib.h
553 @comment ANSI
554 @deftypefun void exit (int @var{status})
555 The @code{exit} function causes normal program termination with status
556 @var{status}.  This function does not return.
557 @end deftypefun
558
559 When a program terminates normally by returning from its @code{main}
560 function or by calling @code{exit}, the following actions occur in
561 sequence:
562
563 @enumerate
564 @item 
565 Functions that were registered with the @code{atexit} or @code{on_exit}
566 functions are called in the reverse order of their registration.  This
567 mechanism allows your application to specify its own ``cleanup'' actions
568 to be performed at program termination.  Typically, this is used to do
569 things like saving program state information in a file, or unlock locks
570 in shared data bases.
571
572 @item 
573 All open streams are closed; writing out any buffered output data.  See
574 @ref{Opening and Closing Streams}.  In addition, temporary files opened
575 with the @code{tmpfile} function are removed; see @ref{Temporary Files}.
576
577 @item 
578 @code{_exit} is called.  @xref{Termination Internals}
579 @end enumerate
580
581 @node Exit Status
582 @subsection Exit Status
583
584 The most common exit status values are zero, meaning success, and one,
585 usually meaning failure of an unspecified nature.  Some programs use
586 other status values so that they can distinguish various kinds of
587 failure.  And sometimes the value of one is used to mean ``false''
588 rather than a real failure.  For example, comparison programs such as
589 @code{cmp} and @code{diff} return 1 as the status code just to indicate
590 that the files compared were not identical.
591
592 @strong{Portability note:} Some non-POSIX systems use different
593 conventions for exit status values.  For greater portability, you can
594 use the macros @code{EXIT_SUCCESS} and @code{EXIT_FAILURE} for the
595 conventional status value for success and failure, respectively.  They
596 are declared in the file @file{stdlib.h}.
597 @pindex stdlib.h
598
599 @comment stdlib.h
600 @comment ANSI
601 @deftypevr Macro int EXIT_SUCCESS
602 This macro can be used with the @code{exit} function to indicate
603 successful program completion.
604
605 On POSIX systems, the value of this macro is @code{0}.  On other
606 systems, the value might be some other (possibly non-constant) integer
607 expression.
608 @end deftypevr
609
610 @comment stdlib.h
611 @comment ANSI
612 @deftypevr Macro int EXIT_FAILURE
613 This macro can be used with the @code{exit} function to indicate
614 unsuccessful program completion in a general sense.
615
616 On POSIX systems, the value of this macro is @code{1}.  On other
617 systems, the value might be some other (possibly non-constant) integer
618 expression.  Other nonzero status values also indicate future.  Certain
619 programs use different nonzero status values to indicate particular
620 kinds of "non-success".  For example, @code{diff} uses status value
621 @code{1} to mean that the files are different, and @code{2} or more to
622 mean that there was difficulty in opening the files.
623 @end deftypevr
624
625 @node Cleanups on Exit
626 @subsection Cleanups on Exit
627
628 @comment stdlib.h
629 @comment ANSI
630 @deftypefun int atexit (void (*@var{function}))
631 The @code{atexit} function registers the function @var{function} to be
632 called at normal program termination.  The @var{function} is called with
633 no arguments.
634
635 The return value from @code{atexit} is zero on success and nonzero if
636 the function cannot be registered. 
637 @end deftypefun
638
639 @comment stdlib.h
640 @comment GNU
641 @deftypefun int on_exit (void (*@var{function})(int @var{status}, void *@var{arg}), void *@var{arg})
642 This function is a somewhat more powerful variant of @code{atexit}.  It
643 accepts two arguments, a function @var{function} and an arbitrary
644 pointer @var{arg}.  At normal program termination, the @var{function} is
645 called with two arguments:  the @var{status} value passed to @code{exit},
646 and the @var{arg}.
647
648 This function is a GNU extension, and may not be supported by other
649 implementations.
650 @end deftypefun
651
652 Here's a trivial program that illustrates the use of @code{exit} and
653 @code{atexit}:
654
655 @example
656 #include <stdio.h>
657 #include <stdlib.h>
658
659 void bye (void)
660 @{
661   printf ("Goodbye, cruel world....\n");
662 @}
663
664 void main (void)
665 @{
666   atexit (bye);
667   exit (EXIT_SUCCESS);
668 @}
669 @end example
670
671 @noindent
672 When this program is executed, it just prints the message and exits.
673
674
675 @node Aborting a Program
676 @subsection Aborting a Program
677 @cindex aborting a program
678
679 You can abort your program using the @code{abort} function.  The prototype
680 for this function is in @file{stdlib.h}.
681 @pindex stdlib.h
682
683 @comment stdlib.h
684 @comment ANSI
685 @deftypefun void abort ()
686 The @code{abort} function causes abnormal program termination, without
687 executing functions registered with @code{atexit} or @code{on_exit}.
688
689 This function actually terminates the process by raising a
690 @code{SIGABRT} signal, and your program can include a handler to
691 intercept this signal; see @ref{Signal Handling}.
692
693 @strong{Incomplete:}  Why would you want to define such a handler?
694 @end deftypefun
695
696 @node Termination Internals
697 @subsection Termination Internals
698
699 The @code{_exit} function is the primitive used for process termination
700 by @code{exit}.  It is declared in the header file @file{unistd.h}.
701 @pindex unistd.h
702
703 @comment unistd.h
704 @comment POSIX.1
705 @deftypefun void _exit (int @var{status})
706 The @code{_exit} function is the primitive for causing a process to
707 terminate with status @var{status}.  Calling this function does not
708 execute cleanup functions registered with @code{atexit} or
709 @code{on_exit}.
710 @end deftypefun
711
712 When a process terminates for any reason---either by an explicit
713 termination call, or termination as a result of a signal---the
714 following things happen:
715
716 @itemize @bullet
717 @item
718 All open file descriptors in the process are closed.  @xref{Low-Level
719 Input/Output}.
720
721 @item
722 The low-order 8 bits of the return status code are saved to be reported
723 back to the parent process via @code{wait} or @code{waitpid}; see
724 @ref{Process Completion}.
725
726 @item
727 Any child processes of the process being terminated are assigned a new
728 parent process.  (This is the @code{init} process, with process ID 1.)
729
730 @item
731 A @code{SIGCHLD} signal is sent to the parent process.
732
733 @item
734 If the process is a session leader that has a controlling terminal, then
735 a @code{SIGHUP} signal is sent to each process in the foreground job,
736 and the controlling terminal is disassociated from that session.
737 @xref{Job Control}.
738
739 @item
740 If termination of a process causes a process group to become orphaned,
741 and any member of that process group is stopped, then a @code{SIGHUP}
742 signal and a @code{SIGCONT} signal are sent to each process in the
743 group.  @xref{Job Control}.
744 @end itemize
745
746 @node Creating New Processes
747 @section Creating New Processes
748
749 This section describes how your program can cause other programs to be
750 executed.  Actually, there are three distinct operations involved:
751 creating a new child process, causing the new process to execute a
752 program, and coordinating the completion of the child process with the
753 original program.
754
755 The @code{system} function provides a simple, portable mechanism for
756 running another program; it does all three steps automatically.  If you
757 need more control over the details of how this is done, you can use the
758 primitive functions to do each step individually instead.
759
760 @menu
761 * Running a Command::                   The easy way to run another program.
762 * Process Creation Concepts::           An overview of the hard way to do it.
763 * Process Identification::              How to get the process ID of a process.
764 * Creating a Process::                  How to fork a child process.
765 * Executing a File::                    How to get a process to execute another
766                                          program.
767 * Process Completion::                  How to tell when a child process has
768                                          completed.
769 * Process Completion Status::           How to interpret the status value 
770                                          returned from a child process.
771 * BSD Process Completion Functions::    More functions, for backward
772                                          compatibility.
773 * Process Creation Example::            A complete example program.
774 @end menu
775
776
777 @node Running a Command
778 @subsection Running a Command
779 @cindex running a command
780
781 The easy way to run another program is to use the @code{system}
782 function.  This function does all the work of running a subprogram, but
783 it doesn't give you much control over the details: you have to wait
784 until the subprogram terminates before you can do anything else.
785
786 @pindex stdlib.h
787
788 @comment stdlib.h
789 @comment ANSI
790 @deftypefun int system (const char *@var{command})
791 This function executes @var{command} as a shell command.  In the GNU C
792 library, it always uses the default shell @code{sh} to run the command.
793 In particular, it searching the directories in @code{PATH} to find
794 programs to execute.  The return value is @code{-1} if it wasn't
795 possible to create the shell process, and otherwise is the status of the
796 shell process.  @xref{Process Completion}, for details on how this
797 status code can be interpreted.
798 @pindex sh
799 @end deftypefun
800
801 The @code{system} function is declared in the header file
802 @file{stdlib.h}.
803
804 @strong{Portability Note:} Some C implementations may not have any
805 notion of a command processor that can execute other programs.  You can
806 determine whether a command processor exists by executing @code{system
807 (o)}; in this case the return value is nonzero if and only if such a
808 processor is available.
809
810 The @code{popen} and @code{pclose} functions (@pxref{Pipe to a
811 Subprocess}) are closely related to the @code{system} function.  They
812 allow the parent process to communicate with the standard input and
813 output channels of the command being executed.
814
815 @node Process Creation Concepts
816 @subsection Process Creation Concepts
817
818 This section gives an overview of processes and of the steps involved in
819 creating a process and making it run another program.
820
821 @cindex process ID
822 @cindex process lifetime
823 Each process is named by a @dfn{process ID} number.  A unique process ID
824 is allocated to each process when it is created.  The @dfn{lifetime} of
825 a process ends when its termination is reported to its parent process;
826 at that time, all of the process resources, including its process ID,
827 are freed.
828
829 @cindex creating a process
830 @cindex forking a process
831 @cindex child process
832 @cindex parent process
833 Processes are created with the @code{fork} system call (so the operation
834 of creating a new process is sometimes called @dfn{forking} a process).
835 The @dfn{child process} created by @code{fork} is an exact clone of the
836 original @dfn{parent process}, except that it has its own process ID.
837
838 After forking a child process, both the parent and child processes
839 continue to execute normally.  If you want your program to wait for a
840 child process to finish executing before continuing, you must do this
841 explicitly after the fork operation.  This is done with the @code{wait}
842 or @code{waitpid} functions (@pxref{Process Completion}).  These
843 functions give the parent information about why the child
844 terminated---for example, its exit status code.
845
846 A newly forked child process continues to execute the same program as
847 its parent process, at the point where the @code{fork} call returns.
848 You can use the return value from @code{fork} to tell whether the program
849 is running in the parent process or the child.
850
851 @cindex process image
852 Having all processes run the same program is usually not very useful.
853 But the child can execute another program using one of the @code{exec}
854 functions; see @ref{Executing a File}.  The program that the process is
855 executing is called its @dfn{process image}.  Starting execution of a
856 new program causes the process to forget all about its current process
857 image; when the new program exits, the process exits too, instead of
858 returning to the previous process image.
859
860
861 @node Process Identification
862 @subsection Process Identification
863
864 The @code{pid_t} data type represents process IDs.  You can get the
865 process ID of a process by calling @code{getpid}.  The function
866 @code{getppid} returns the process ID of the parent of the parent of the
867 current process (this is also known as the @dfn{parent process ID}).
868 Your program should include the header files @file{unistd.h} and
869 @file{sys/types.h} to use these functions.
870 @pindex sys/types.h
871 @pindex unistd.h
872
873 @comment sys/types.h
874 @comment POSIX.1
875 @deftp {Data Type} pid_t
876 The @code{pid_t} data type is a signed integer type which is capable
877 of representing a process ID.  In the GNU library, this is an @code{int}.
878 @end deftp
879
880 @comment unistd.h
881 @comment POSIX.1
882 @deftypefun pid_t getpid ()
883 The @code{getpid} function returns the process ID of the current process.
884 @end deftypefun
885
886 @comment unistd.h
887 @comment POSIX.1
888 @deftypefun pid_t getppid ()
889 The @code{getppid} function returns the process ID of the parent of the
890 current process.
891 @end deftypefun
892
893 @node Creating a Process
894 @subsection Creating a Process
895
896 The @code{fork} function is the primitive for creating a process.
897 It is declared in the header file @file{unistd.h}.
898 @pindex unistd.h
899
900 @comment unistd.h
901 @comment POSIX.1
902 @deftypefun pid_t fork ()
903 The @code{fork} function creates a new process.
904
905 If the operation is successful, there are then both parent and child
906 processes and both see @code{fork} return, but with different values: it
907 returns a value of @code{0} in the child process and returns the child's
908 process ID in the parent process.  If the child process could not be
909 created, a value of @code{-1} is returned in the parent process.  The
910 following @code{errno} error conditions are defined for this function:
911
912 @table @code
913 @item EAGAIN
914 There aren't enough system resources to create another process, or the
915 user already has too many processes running.
916
917 @item ENOMEM
918 The process requires more space than the system can supply.
919 @end table
920 @end deftypefun
921
922 The specific attributes of the child process that differ from the
923 parent process are:
924
925 @itemize @bullet
926 @item
927 The child process has its own unique process ID.
928
929 @item
930 The parent process ID of the child process is the process ID of its
931 parent process.
932
933 @item
934 The child process gets its own copies of the parent process's open file
935 descriptors.  Subsequently changing attributes of the file descriptors
936 in the parent process won't affect the file descriptors in the child,
937 and vice versa.  @xref{Control Operations}.
938
939 @item
940 The elapsed processor times for the child process are set to zero;
941 see @ref{Processor Time}.
942
943 @item
944 The child doesn't inherit file locks set by the parent process.
945 @xref{Control Operations}.
946
947 @item
948 The child doesn't inherit alarms set by the parent process.
949 @xref{Setting an Alarm}.
950
951 @item
952 The set of pending signals (@pxref{Delivery of Signal}) for the child
953 process is cleared.  (The child process inherits its mask of blocked
954 signals and signal actions from the parent process.)
955 @end itemize 
956
957
958 @comment unistd.h
959 @comment BSD
960 @deftypefun pid_t vfork (void)
961 The @code{vfork} function is similar to @code{fork} but more efficient;
962 however, there are restrictions you must follow to use it safely.
963
964 While @code{fork} makes a complete copy of the calling process's address
965 space and allows both the parent and child to execute independently,
966 @code{vfork} does not make this copy.  Instead, the child process
967 created with @code{vfork} shares its parent's address space until it calls
968 one of the @code{exec} functions.  In the meantime, the parent process
969 suspends execution.
970
971 You must be very careful not to allow the child process created with
972 @code{vfork} to modify any global data or even local variables shared
973 with the parent.  Furthermore, the child process cannot return from (or
974 do a long jump out of) the function that called @code{vfork}!  This
975 would leave the parent process's control information very confused.  If
976 in doubt, use @code{fork} instead.
977
978 Some operating systems don't really implement @code{vfork}.  The GNU C
979 library permits you to use @code{vfork} on all systems, but actually
980 executes @code{fork} if @code{vfork} isn't available.
981 @end deftypefun
982
983 @node Executing a File
984 @subsection Executing a File
985 @cindex executing a file
986 @cindex @code{exec} functions
987
988 This section describes the @code{exec} family of functions, for executing
989 a file as a process image.  You can use these functions to make a child
990 process execute a new program after it has been forked.
991
992 The functions in this family differ in how you specify the arguments,
993 but otherwise they all do the same thing.  They are declared in the
994 header file @file{unistd.h}.
995 @pindex unistd.h
996
997 @comment unistd.h
998 @comment POSIX.1
999 @deftypefun int execv (const char *@var{filename}, char *const @var{argv}@t{[]})
1000 The @code{execv} function executes the file named by @var{filename} as a
1001 new process image.
1002
1003 The @var{argv} argument is an array of null-terminated strings that is
1004 used to provide a value for the @code{argv} argument to the @code{main}
1005 function of the program to be executed.  The last element of this array
1006 must be a null pointer.  @xref{Program Arguments}, for information on
1007 how programs can access these arguments.
1008
1009 The environment for the new process image is taken from the
1010 @code{environ} variable of the current process image; see @ref{Environment
1011 Variables}, for information about environments.
1012 @end deftypefun
1013
1014 @comment unistd.h
1015 @comment POSIX.1
1016 @deftypefun int execl (const char *@var{filename}, const char *@var{arg0}, @dots{})
1017 This is similar to @code{execv}, but the @var{argv} strings are
1018 specified individually instead of as an array.  A null pointer must be
1019 passed as the last such argument.
1020 @end deftypefun
1021
1022 @comment unistd.h
1023 @comment POSIX.1
1024 @deftypefun int execve (const char *@var{filename}, char *const @var{argv}@t{[]}, char *const @var{env}@t{[]})
1025 This is similar to @code{execv}, but permits you to specify the environment
1026 for the new program explicitly as the @var{env} argument.  This should
1027 be an array of strings in the same format as for the @code{environ} 
1028 variable; see @ref{Environment Access}.
1029 @end deftypefun
1030
1031 @comment unistd.h
1032 @comment POSIX.1
1033 @deftypefun int execle (const char *@var{filename}, const char *@var{arg0}, char *const @var{env}@t{[]}, @dots{})
1034 This is similar to @code{execl}, but permits you to specify the
1035 environment for the new program explicitly.  The environment argument is
1036 passed following the null pointer that marks the last @var{argv}
1037 argument, and should be an array of strings in the same format as for
1038 the @code{environ} variable.
1039 @end deftypefun
1040
1041 @comment unistd.h
1042 @comment POSIX.1
1043 @deftypefun int execvp (const char *@var{filename}, char *const @var{argv}@t{[]})
1044 The @code{execvp} function is similar to @code{execv}, except that it
1045 searches the directories listed in the @code{PATH} environment variable
1046 (@pxref{Standard Environment Variables}) to find the full file name of a
1047 file from @var{filename} if @var{filename} does not contain a slash.
1048
1049 This function is useful for executing installed system utility programs,
1050 so that the user can control where to look for them.  It is also useful
1051 in shells, for executing commands typed by the user.
1052 @end deftypefun
1053
1054 @comment unistd.h
1055 @comment POSIX.1
1056 @deftypefun int execlp (const char *@var{filename}, const char *@var{arg0}, @dots{})
1057 This function is like @code{execl}, except that it performs the same
1058 file name searching as the @code{execvp} function.
1059 @end deftypefun
1060
1061
1062 The size of the argument list and environment list taken together must not
1063 be greater than @code{ARG_MAX} bytes.  @xref{System Parameters}.
1064
1065 @strong{Incomplete:}  The POSIX.1 standard requires some statement here
1066 about how null terminators, null pointers, and alignment requirements
1067 affect the total size of the argument and environment lists.
1068
1069 These functions normally don't return, since execution of a new program
1070 causes the currently executing program to go away completely.  A value
1071 of @code{-1} is returned in the event of a failure.  In addition to the
1072 usual file name syntax errors (@pxref{File Name Errors}), the following
1073 @code{errno} error conditions are defined for these functions:
1074
1075 @table @code
1076 @item E2BIG
1077 The combined size of the new program's argument list and environment list
1078 is larger than @code{ARG_MAX} bytes.
1079
1080 @item ENOEXEC
1081 The specified file can't be executed because it isn't in the right format.
1082
1083 @item ENOMEM
1084 Executing the specified file requires more storage than is available.
1085 @end table
1086
1087 If execution of the new file is successful, the access time field of the
1088 file is updated as if the file had been opened.  @xref{File Times}, for
1089 more details about access times of files.
1090
1091 The point at which the file is closed again is not specified, but
1092 is at some point before the process exits or before another process
1093 image is executed.
1094
1095 Executing a new process image completely changes the contents of memory,
1096 except for the arguments and the environment, but many other attributes
1097 of the process are unchanged:
1098
1099 @itemize @bullet
1100 @item
1101 The process ID and the parent process ID.  @xref{Process Creation Concepts}.
1102
1103 @item
1104 Session and process group membership.  @xref{Job Control Concepts}.
1105
1106 @item
1107 Real user ID and group ID, and supplementary group IDs.  @xref{User/Group
1108 IDs of a Process}.
1109
1110 @item
1111 Pending alarms.  @xref{Setting an Alarm}.
1112
1113 @item
1114 Current working directory and root directory.  @xref{Working Directory}.
1115
1116 @item
1117 File mode creation mask.  @xref{Setting Permissions}.
1118
1119 @item
1120 Process signal mask; see @ref{Process Signal Mask}.
1121
1122 @item
1123 Pending signals; see @ref{Blocking Signals}.
1124
1125 @item
1126 Elapsed processor time associated with the process; see @ref{Processor Time}.
1127 @end itemize
1128
1129 If the set-user-ID and set-group-ID mode bits of the process image file
1130 are set, this affects the effective user ID and effective group ID
1131 (respectively) of the process.  These concepts are discussed in detail
1132 in @ref{User/Group IDs of a Process}.
1133
1134 Signals that are set to be ignored in the existing process image are
1135 also set to be ignored in the new process image.  All other signals are
1136 set to the default action in the new process image.  For more
1137 information about signals, see @ref{Signal Handling}.
1138
1139 File descriptors open in the existing process image remain open in the
1140 new process image, unless they have the @code{FD_CLOEXEC}
1141 (close-on-exec) flag set.  The files that remain open inherit all
1142 attributes of the open file description from the existing process image,
1143 including file locks.  File descriptors are discussed in @ref{Low-Level
1144 Input/Output}.
1145
1146 Streams, by contrast, cannot survive through @code{exec} functions,
1147 because they are located in the memory of the process itself.  The new
1148 process image has no streams except those it creates afresh.  Each of
1149 the streams in the pre-@code{exec} process image has a descriptor inside
1150 it, and these descriptors do survive through @code{exec} (provided that
1151 they do not have @code{FD_CLOEXEC} set.  The new process image can
1152 reconnect these to new streams using @code{fdopen}.
1153
1154 @node Process Completion
1155 @subsection Process Completion
1156 @cindex process completion
1157 @cindex waiting for completion of child process
1158 @cindex testing exit status of child process
1159
1160 The functions described in this section are used to wait for a child
1161 process to terminate or stop, and determine its status.  These functions
1162 are declared in the header file @file{sys/wait.h}.
1163 @pindex sys/wait.h
1164
1165 @comment sys/wait.h
1166 @comment POSIX.1
1167 @deftypefun pid_t waitpid (pid_t @var{pid}, int *@var{status_ptr}, int @var{options})
1168 The @code{waitpid} function is used to request status information from a
1169 child process whose process ID is @var{pid}.  Normally, the calling
1170 process is suspended until the child process makes status information
1171 available by terminating.
1172
1173 Other values for the @var{pid} argument have special interpretations.  A
1174 value of @code{-1} or @code{WAIT_ANY} requests status information for
1175 any child process; a value of @code{0} or @code{WAIT_MYPGRP} requests
1176 information for any child process in the same process group as the
1177 calling process; and any other negative value @minus{} @var{pgid}
1178 requests information for any child process whose process group ID is
1179 @var{pgid}.
1180
1181 If status information for a child process is available immediately, this
1182 function returns immediately without waiting.  If more than one eligible
1183 child process has status information available, one of them is chosen
1184 randomly, and its status is returned immediately.  To get the status
1185 from the other programs, you need to call @code{waitpid} again.
1186
1187 The @var{options} argument is a bit mask.  Its value should be the
1188 bitwise OR (that is, the @samp{|} operator) of zero or more of the
1189 @code{WNOHANG} and @code{WUNTRACED} flags.  You can use the
1190 @code{WNOHANG} flag to indicate that the parent process shouldn't wait;
1191 and the @code{WUNTRACED} flag to request status information from stopped
1192 processes as well as processes that have terminated.
1193
1194 The status information from the child process is stored in the object
1195 that @var{status_ptr} points to, unless @var{status_ptr} is a null pointer.
1196
1197 The return value is normally the process ID of the child process whose
1198 status is reported.  If the @code{WNOHANG} option was specified and no
1199 child process is waiting to be noticed, a value of zero is returned.  A
1200 value of @code{-1} is returned in case of error.  The following
1201 @code{errno} error conditions are defined for this function:
1202
1203 @table @code
1204 @item EINTR
1205 The function was interrupted by delivery of a signal to the calling
1206 process.
1207
1208 @item ECHILD
1209 There are no child processes to wait for, or the specified @var{pid}
1210 is not a child of the calling process.
1211
1212 @item EINVAL
1213 An invalid value was provided for the @var{options} argument.
1214 @end table
1215 @end deftypefun
1216
1217 These symbolic constants are defined as values for the @var{pid} argument
1218 to the @code{waitpid} function.
1219
1220 @table @code
1221 @item WAIT_ANY
1222 This constant macro (whose value is @code{-1}) specifies that
1223 @code{waitpid} should return status information about any child process.
1224
1225 @item WAIT_MYPGRP
1226 This constant (with value @code{0}) specifies that @code{waitpid} should
1227 return status information about any child process in the same process
1228 group as the calling process.
1229
1230 These symbolic constants are defined as flags for the @var{options}
1231 argument to the @code{waitpid} function.  You can bitwise-OR the flags
1232 together to obtain a value to use as the argument.
1233
1234 @item WNOHANG
1235 This flag specifies that @code{waitpid} should return immediately
1236 instead of waiting if there is no child process ready to be noticed.
1237
1238 @item WUNTRACED
1239 This macro is used to specify that @code{waitpid} should also report the
1240 status of any child processes that have been stopped as well as those
1241 that have terminated.
1242 @end table
1243
1244 @deftypefun pid_t wait (int *@var{status_ptr})
1245 This is a simplified version of @code{waitpid}, and is used to wait
1246 until any one child process terminates.
1247
1248 @example
1249 wait (&status)
1250 @end example
1251
1252 @noindent
1253 is equivalent to:
1254
1255 @example
1256 waitpid (-1, &status, 0)
1257 @end example
1258
1259 Here's an example of how to use @code{waitpid} to get the status from
1260 all child processes that have terminated, without ever waiting.  This
1261 function is designed to be used as a handler for @code{SIGCHLD}, the
1262 signal that indicates that at least one child process has terminated.
1263
1264 @example
1265 void
1266 sigchld_handler (int signum)
1267 @{
1268   int pid;
1269   int status;
1270   while (1) @{
1271     pid = waitpid (WAIT_ANY, Estatus, WNOHANG);
1272     if (pid < 0) @{
1273       perror ("waitpid");
1274       break;
1275     @}
1276     if (pid == 0)
1277       break;
1278     notice_termination (pid, status);
1279   @}
1280 @}
1281 @end example
1282 @end deftypefun
1283
1284 @node Process Completion Status
1285 @subsection Process Completion Status
1286
1287 If the exit status value (@pxref{Program Termination}) of the child
1288 process is zero, then the status value reported by @code{waitpid} or
1289 @code{wait} is also zero.  You can test for other kinds of information
1290 encoded in the returned status value using the following macros.
1291 These macros are defined in the header file @file{sys/wait.h}.
1292 @pindex sys/wait.h
1293
1294 @comment sys/wait.h
1295 @comment POSIX.1
1296 @deftypefn Macro int WIFEXITED (int @var{status})
1297 This macro returns a non-zero value if the child process terminated
1298 normally with @code{exit} or @code{_exit}.
1299 @end deftypefn
1300
1301 @comment sys/wait.h
1302 @comment POSIX.1
1303 @deftypefn Macro int WEXITSTATUS (int @var{status})
1304 If @code{WIFEXITED} is true of @var{status}, this macro returns the
1305 low-order 8 bits of the exit status value from the child process.
1306 @end deftypefn
1307
1308 @comment sys/wait.h
1309 @comment POSIX.1
1310 @deftypefn Macro int WIFSIGNALED (int @var{status})
1311 This macro returns a non-zero value if the child process terminated
1312 by receiving a signal that was not handled.
1313 @end deftypefn
1314
1315 @comment sys/wait.h
1316 @comment POSIX.1
1317 @deftypefn Macro int WTERMSIG (int @var{status})
1318 If @code{WIFSIGNALED} is true of @var{status}, this macro returns the
1319 number of the signal that terminated the child process.
1320 @end deftypefn
1321
1322 @comment sys/wait.h
1323 @comment BSD
1324 @deftypefn Macro int WCOREDUMP (int @var{status})
1325 This macro returns a non-zero value if the child process terminated
1326 and produced a core dump.
1327 @end deftypefn
1328
1329 @comment sys/wait.h
1330 @comment POSIX.1
1331 @deftypefn Macro int WIFSTOPPED (int @var{status})
1332 This macro returns a non-zero value if the child process is stopped.
1333 @end deftypefn
1334
1335 @comment sys/wait.h
1336 @comment POSIX.1
1337 @deftypefn Macro int WSTOPSIG (int @var{status})
1338 If @code{WIFSTOPPED} is true of @var{status}, this macro returns the
1339 number of the signal that caused the child process to stop.
1340 @end deftypefn
1341
1342
1343 @node BSD Process Completion Functions
1344 @subsection BSD Process Completion Functions
1345
1346 The GNU library also provides these related facilities for compatibility
1347 with BSD Unix.  BSD uses the @code{union wait} data type to represent
1348 status values rather than an @code{int}.  The two representations are
1349 actually interchangeable; they describe the same bit patterns. The macros
1350 such as @code{WEXITSTATUS} are defined so that they will work on either
1351 kind of object, and the @code{wait} function is defined to accept either
1352 type of pointer as its @var{status_ptr} argument.
1353
1354 These functions are declared in @file{sys/wait.h}.
1355 @pindex sys/wait.h
1356
1357 @comment sys/wait.h
1358 @comment BSD
1359 @deftp {union Type} wait
1360 This data type represents program termination status values.  It has
1361 the following members:
1362
1363 @table @code
1364 @item int w_termsig
1365 This member is equivalent to the @code{WTERMSIG} macro.
1366
1367 @item int w_coredump
1368 This member is equivalent to the @code{WCOREDUMP} macro.
1369
1370 @item int w_retcode
1371 This member is equivalent to the @code{WEXISTATUS} macro.
1372
1373 @item int w_stopsig
1374 This member is equivalent to the @code{WSTOPSIG} macro.
1375 @end table
1376
1377 Instead of accessing these members directly, you should use the
1378 equivalent macros.
1379 @end deftp
1380
1381 @comment sys/wait.h
1382 @comment BSD
1383 @deftypefun pid_t wait3 (union wait *@var{status_ptr}, int @var{options}, void * @var{usage})
1384 If @var{usage} is a null pointer, this function is equivalent to
1385 @code{waitpid (-1, @var{status_ptr}, @var{options})}.
1386
1387 The @var{usage} argument may also be a pointer to a 
1388 @code{struct rusage} object.  Information about system resources used by
1389 terminated processes (but not stopped processes) is returned in this
1390 structure.
1391
1392 @strong{Incomplete:}  The description of the @code{struct rusage} structure
1393 hasn't been written yet.  Put in a cross-reference here.
1394 @end deftypefun
1395
1396 @comment sys/wait.h
1397 @comment BSD
1398 @deftypefun pid_t wait4 (pid_t @var{pid}, union wait *@var{status_ptr}, int @var{options}, void *@var{usage})
1399 If @var{usage} is a null pointer, this function is equivalent to
1400 @code{waitpid (@var{pid}, @var{status_ptr}, @var{options})}.
1401
1402 The @var{usage} argument may also be a pointer to a 
1403 @code{struct rusage} object.  Information about system resources used by
1404 terminated processes (but not stopped processes) is returned in this
1405 structure.
1406
1407 @strong{Incomplete:}  The description of the @code{struct rusage} structure
1408 hasn't been written yet.  Put in a cross-reference here.
1409 @end deftypefun
1410
1411 @node Process Creation Example
1412 @subsection Process Creation Example
1413
1414 Here is an example program showing how you might write a function
1415 similar to the built-in @code{system}.  It executes its @var{command}
1416 argument using the equivalent of @samp{sh -c @var{command}}.
1417
1418 @example
1419 #include <stddef.h>
1420 #include <stdlib.h>
1421 #include <unistd.h>
1422 #include <sys/types.h>
1423 #include <sys/wait.h>
1424
1425 /* @r{Execute the command using this shell program.}  */
1426 #define SHELL "/bin/sh"
1427
1428 int 
1429 my_system (char *command)
1430 @{
1431   int status;
1432   pid_t pid;
1433
1434   pid =  fork ();
1435   if (pid == 0) @{
1436     /* @r{This is the child process.  Execute the shell command.} */
1437     execl (SHELL, SHELL, "-c", command, NULL);
1438     exit (EXIT_FAILURE);
1439   @}
1440   else if (pid < 0)
1441     /* @r{The fork failed.  Report failure.}  */
1442     status = -1;
1443   else @{
1444     /* @r{This is the parent process.  Wait for the child to complete.}  */
1445     if (waitpid (pid, &status, 0) != pid)
1446       status = -1;
1447   @}
1448   return status;
1449 @}
1450 @end example
1451
1452 @comment Yes, this example has been tested.
1453
1454 There are a couple of things you should pay attention to in this
1455 example.
1456
1457 Remember that the first @code{argv} argument supplied to the program
1458 represents the name of the program being executed.  That is why, in the
1459 call to @code{execl}, @code{SHELL} is supplied once to name the program
1460 to execute and a second time to supply a value for @code{argv[0]}.  
1461
1462 The @code{execl} call in the child process doesn't return if it is
1463 successful.  If it fails, you must do something to make the child
1464 process terminate.  Just returning a bad status code with @code{return}
1465 would leave two processes running the original program.  Instead, the
1466 right behavior is for the child process to report failure to its parent
1467 process.  To do this, @code{exit} is called with a failure status.
1468
1469 @node User/Group IDs of a Process
1470 @section User/Group IDs of a Process
1471
1472 @cindex process ownership
1473 @cindex process, user ID of
1474 @cindex process, group ID of
1475 @cindex @code{setuid} program
1476 @cindex @code{setgid} program
1477
1478 When the system decides whether a process can access a file, it starts
1479 by comparing the user and group IDs of the process with those of the
1480 file.
1481
1482 Normally, a process inherits its user and group IDs from its parent
1483 process, but a program can change them so that it can access resources
1484 that wouldn't otherwise be available to it.
1485
1486 @menu
1487 * Process User and Group IDs::          Defines terms and concepts.
1488 * Changing the User or Group ID::       Why a program might need to change
1489                                          its user and/or group IDs.
1490 * Controlling Process Privileges::      Restrictions on how the user and
1491                                          group IDs can or should be changed.
1492 * User and Group ID Functions::         Detailed specification of the
1493                                          interface.
1494 * Setuid Program Example::              A detailed example.
1495 @end menu
1496
1497 @node Process User and Group IDs
1498 @subsection Process User and Group IDs
1499
1500 @cindex login name
1501 @cindex user name
1502 @cindex user ID
1503 Each user account on a computer system is identified by a @dfn{user
1504 name} (or @dfn{login name}) and @dfn{user ID}.  Normally, each login
1505 name in the database has a unique user ID, but it is possible for
1506 several login names to have the same user ID.
1507
1508 @cindex group name
1509 @cindex group ID
1510 Users are classified in @dfn{groups}.  Each user name also belongs to
1511 one or more groups, and has one @dfn{default group}.  Users who are
1512 members of the same group can share resources (such as files) that are
1513 not accessible to users who are not a member of that group.  Each group
1514 has a @dfn{group name} and @dfn{group ID}.
1515
1516 When you log in to the computer, the processes that you create are
1517 assigned your user ID and your default group ID.
1518
1519 @cindex effective user ID
1520 @cindex real user ID
1521 A particular process actually has two user IDs associated with it.  The
1522 @dfn{real user ID} identifies the user who created the process.  The
1523 @dfn{effective user ID}, on the other hand, is used to determine
1524 permissions for accessing resources such as files.  Both the real and
1525 effective user ID can be changed during the lifetime of a process.
1526 @xref{Changing the User or Group ID}.
1527
1528 @cindex real group ID
1529 @cindex effective group ID
1530 @cindex supplementary group IDs
1531 Similarly, an individual process has both @dfn{real group ID} and
1532 @dfn{effective group ID} attributes.  In addition, a user can belong to
1533 multiple groups, so a process can have @dfn{supplementary group IDs}.
1534 that also contribute to access permission.
1535
1536 For details on how a process's user IDs and group IDs affect its
1537 permission to access files, see @ref{Access Permission}.  For
1538 more information about the system user and group databases,
1539 see @ref{System Databases}.
1540
1541 The user ID of a process also controls permissions for sending signals
1542 using the @code{kill} function.  @xref{Signaling Another Process}.
1543
1544
1545
1546 @node Changing the User or Group ID
1547 @subsection Changing the User or Group ID
1548
1549 The most obvious situation where it is necessary for a process to change
1550 its user and/or group IDs is the @code{login} program.  When
1551 @code{login} starts running, its user ID is @code{root}.  Its job is to
1552 start a shell whose user and group IDs are those of the user who is
1553 logging in.
1554
1555 Some ordinary user programs also need to use an effective user or group
1556 ID that corresponds to something other than the user who is actually
1557 running the program.  This permits the program to use a resource that
1558 wouldn't otherwise be accessible to the user.  For example, you may have
1559 a file that is controlled by your program but that shouldn't be read or
1560 modified directly by ordinary users, either because it implements some
1561 kind of locking protocol, or because you want to be careful to preserve
1562 the integrity or privacy of the information it contains.  This kind of
1563 restricted access can be implemented by having the program change its
1564 user or group ID to be the same as the owner of the resource.
1565
1566 Thus, imagine a game program that saves scores in a file.  The game
1567 program itself obviously needs to be able to update this file no matter
1568 who is running it, but if users can write the file without going through
1569 the game, they can give themselves any scores they like.  Some people
1570 consider this undesirable; or even reprehensible.  It can be prevented
1571 by creating a new user ID and login name (say, @samp{games}) to own the
1572 scores file, and make the file writable only by this user.  Then, when
1573 the game program wants to update this file, it can change its effective
1574 user ID to be that for @samp{games}.
1575
1576 @comment The example of phone bills was deleted by RMS because it endorses 
1577 @comment a way of running a computer facility that he detests.
1578
1579 @node Controlling Process Privileges
1580 @subsection Controlling Process Privileges
1581 @cindex restrictions on @code{setuid} programs
1582
1583 The ability to change the user ID of a process can be a source of
1584 unintentional privacy violations, or even intentional abuse.  Because of
1585 the potential for problems, there are a number of restrictions on how
1586 nonprivileged programs can use the facilities, and some guidelines you
1587 should follow in writing such programs.
1588
1589 You can't just arbitrarily set your user ID or group ID to anything you
1590 want; only privileged users can do that.  Instead, the normal way for a
1591 program to change its user or group ID is that it has been set up in
1592 advance to change to a particular user or group.  This is the function
1593 of the suid and sgid bits.  When the suid bit of an executable file is
1594 set, executing that file automatically changes the effective user ID to
1595 the user that owns the file.  Likewise, executing a file whose sgid bit
1596 is set changes the effective group ID to the group of the file.
1597 @xref{Executing a File}.  Creating a file that changes to a particular
1598 user or group ID thus requires full access to that user or group ID.
1599
1600 @xref{File Attributes}, for a more general discussion of file modes and
1601 accessibility.
1602
1603 A process can always change its effective user (or group) ID back to its
1604 real ID.  This is often done because the program doesn't need the
1605 special privileges all the time.
1606
1607 @node Reading User and Group IDs
1608 @subsection Reading User and Group IDs 
1609
1610 Here are detailed descriptions of the functions for inquiring about or
1611 changing the user and group IDs of a process.  To use these facilities,
1612 you must include the header files @file{sys/types.h} and
1613 @file{unistd.h}.
1614 @pindex unistd.h
1615 @pindex sys/types.h
1616
1617 @comment sys/types.h
1618 @comment POSIX.1
1619 @deftp {Data Type} uid_t
1620 This is an integer data type used to represent user IDs.  In the GNU
1621 library, this is an alias for @code{unsigned short int}.
1622 @end deftp
1623
1624 @comment sys/types.h
1625 @comment POSIX.1
1626 @deftp {Data Type} gid_t
1627 This is an integer data type used to represent group IDs.  In the GNU
1628 library, this is an alias for @code{unsigned short int}.
1629 @end deftp
1630
1631 @comment unistd.h
1632 @comment POSIX.1
1633 @deftypefun uid_t getuid ()
1634 The @code{getuid} function returns the real user ID of the process.
1635 @end deftypefun
1636
1637 @comment unistd.h
1638 @comment POSIX.1
1639 @deftypefun gid_t getgid ()
1640 The @code{getgid} function returns the real group ID of the process.
1641 @end deftypefun
1642
1643 @comment unistd.h
1644 @comment POSIX.1
1645 @deftypefun uid_t geteuid ()
1646 The @code{geteuid} function returns the effective user ID of the process.
1647 @end deftypefun
1648
1649 @comment unistd.h
1650 @comment POSIX.1
1651 @deftypefun gid_t getegid ()
1652 The @code{getegid} function returns the effective group ID of the process.
1653 @end deftypefun
1654
1655 @comment unistd.h
1656 @comment POSIX.1
1657 @deftypefun int getgroups (int @var{count}, gid_t *@var{groups})
1658 The @code{getgroups} function is used to inquire about the supplementary
1659 group IDs of the process.  Up to @var{count} of these group IDs are
1660 stored in the array @var{groups}; the return value from the function is
1661 the number of group IDs actually stored.  If @var{count} is smaller than
1662 the total number of supplementary group IDs, then @code{getgroups}
1663 returns a value of @code{-1} and @code{errno} is set to @code{EINVAL}.
1664
1665 If @var{count} is zero, then @code{getgroups} just returns the total
1666 number of supplementary group IDs.
1667
1668 Here's how to use @code{getgroups} to read all the supplementary group
1669 IDs:
1670
1671 @example
1672 gid_t *
1673 read_all_groups ()
1674 @{
1675   int ngroups = getgroups (0, 0);
1676   gid_t *groups = (gid_t *) xmalloc (ngroups * sizeof (gid_t));
1677   int val = getgroups (ngroups, groups);
1678   if (val < 0)
1679     return 0;
1680   return groups;
1681 @}
1682 @end example
1683 @end deftypefun
1684
1685 @comment unistd.h
1686 @comment POSIX.1
1687
1688 @node Setting Uids
1689 @subsection Setting User IDs
1690
1691 @deftypefun int setuid (@var{newuid})
1692 This function sets both the real and effective user ID of the process
1693 to @var{newuid}, provided that the process has appropriate privileges.
1694
1695 If the process is not privileged, then @var{newuid} must either be equal
1696 to the real user ID or the saved user ID from the program's image file
1697 (but only if the implementation supports the @code{_POSIX_SAVED_IDS}
1698 feature).  In this case, @code{setuid} sets only the effective user ID
1699 and not the real user ID.
1700
1701 The @code{setuid} function returns a value of @code{0} to indicate
1702 successful completion, and a value of @code{-1} to indicate an error.
1703 The following @code{errno} error conditions are defined for this
1704 function:
1705
1706 @table @code
1707 @item EINVAL
1708 The value of the @var{newuid} argument is invalid.
1709
1710 @item EPERM
1711 The process does not have the appropriate privileges; you do not
1712 have permission to change to the specified ID.  @xref{Controlling Process
1713 Privileges}.
1714 @end table
1715 @end deftypefun
1716
1717 @comment unistd.h
1718 @comment BSD
1719 @deftypefun int setreuid (int @var{ruid}, int @var{euid})
1720 This function sets the real user ID of the process to @var{ruid} and
1721 the effective user ID to @var{euid}.
1722
1723 The @code{setreuid} function is provided for compatibility with 4.2 BSD
1724 Unix, which does not support saved IDs.  You can use this function to
1725 swap the effective and real user IDs of the process.  (Privileged users
1726 can make other changes as well.)  If saved IDs are supported, you should
1727 use that feature instead of this function.
1728
1729 The return value is @code{0} on success and @code{-1} on failure.
1730 The following @code{errno} error conditions are defined for this
1731 function:
1732
1733 @table @code
1734 @item EPERM
1735 The process does not have the appropriate privileges; you do not
1736 have permission to change to the specified ID.  @xref{Controlling Process
1737 Privileges}.
1738 @end table
1739 @end deftypefun
1740
1741 @comment unistd.h
1742 @comment POSIX.1
1743
1744 @node Setting Groups
1745 @subsection Setting Group IDs
1746
1747 @deftypefun int setgid (@var{newgid})
1748 This function sets both the real and effective group ID of the process
1749 to @var{newgid}, provided that the process has appropriate privileges.
1750
1751 If the process is not privileged, then @var{newgid} must either be equal
1752 to the real group ID or the saved group ID from the program's image
1753 file.  In this case, @code{setgid} sets only the effective group ID and
1754 not the real group ID.
1755
1756 The return values and error conditions for @code{setgid} are the same
1757 as those for @code{setuid}.
1758 @end deftypefun
1759
1760
1761 @comment unistd.h
1762 @comment BSD
1763 @deftypefun int setregid (int @var{rgid}, int @var{egid})
1764 This function sets the real group ID of the process to @var{rgid} and
1765 the effective group ID to @var{egid}.
1766
1767 The @code{setregid} function is provided for compatibility with 4.2 BSD
1768 Unix, which does not support saved IDs.  You can use this function to
1769 swap the effective and real group IDs of the process.  (Privileged users
1770 can make other changes.)  If saved IDs are supported, you should make use 
1771 of that feature instead of using this function.
1772
1773 The return values and error conditions for @code{setregid} are the same
1774 as those for @code{setreuid}.
1775 @end deftypefun
1776
1777 The GNU system also lets privileged processes change their supplementary 
1778 group IDs.  To use @code{setgroups} or @code{initgroups}, your programs
1779 should include the header file @file{grp.h}.
1780 @pindex grp.h
1781
1782 @comment grp.h
1783 @comment BSD
1784 @deftypefun int setgroups (size_t @var{count}, gid_t *@var{groups})
1785 This function sets the process's supplementary group IDs.  It can only
1786 be called from privileged processes.  The @var{count} argument specifies
1787 the number of group IDs in the array @var{groups}.
1788
1789 This function returns @code{0} if successful and @code{-1} on error.
1790 The following @code{errno} error conditions are defined for this
1791 function:
1792
1793 @table @code
1794 @item EPERM
1795 The calling process is not privileged.
1796 @end table
1797 @end deftypefun
1798
1799 @comment grp.h
1800 @comment BSD
1801 @deftypefun int initgroups (const char *@var{user}, gid_t @var{gid})
1802 The @code{initgroups} function effectively calls @code{setgroups} to
1803 set the process's supplementary group IDs to be the normal default for
1804 the user name @var{user}.  The group ID @var{gid} is also included.
1805 @end deftypefun
1806
1807 @node Enable/Disable Setuid
1808 @subsection Turning Setuid Access On and Off
1809
1810 You can use @code{setreuid} to swap the real and effective user IDs of
1811 the process, as follows:
1812
1813 @example
1814 setreuid (geteuid (), getuid ());
1815 @end example
1816
1817 @noindent
1818 This special case is always allowed---it cannot fail.  A @code{setuid}
1819 program can use this to turn its special access on and off.  For
1820 example, suppose a game program has just started, and its real user ID
1821 is @code{jdoe} while its effective user ID is @code{games}.  In this
1822 state, the game can write the scores file.  If it swaps the two uids,
1823 the real becomes @code{games} and the effective becomes @code{jdoe}; now
1824 the program has only @code{jdoe} to access.  Another swap brings
1825 @code{games} back to the effective user ID and restores access to the
1826 scores file.
1827
1828 If the system supports the saved user ID feature, you can accomplish 
1829 the same job with @code{setuid}.  When the game program starts, its
1830 real user ID is @code{jdoe}, its effective user ID is @code{games}, and
1831 its saved user ID is also @code{games}.  The program should record both
1832 user ID values once at the beginning, like this:
1833
1834 @example
1835 user_user_id = getuid ();
1836 game_user_id = geteuid ();
1837 @end example
1838
1839 Then it can turn off game file access with 
1840
1841 @example
1842 setuid (user_user_id);
1843 @end example
1844
1845 @noindent
1846 and turn it on with 
1847
1848 @example
1849 setuid (game_user_id);
1850 @end example
1851
1852 @noindent
1853 Throughout the process, the real user ID remains @code{jdoe} and the 
1854 saved user ID remains @code{games}.
1855
1856 @node Setuid Program Example
1857 @subsection Setuid Program Example
1858
1859 Here's an example showing how to set up a program that changes its
1860 effective user ID.
1861
1862 This is part of a game program called @code{caber-toss} that
1863 manipulates a file @file{scores} that should be writable only by the game
1864 program itself.  The program assumes that its executable
1865 file will be installed with the set-user-ID bit set and owned by the
1866 same user as the @file{scores} file.  Typically, a system
1867 administrator will set up an account like @samp{games} for this purpose.
1868
1869 The executable file is given mode @code{4755}, so that doing an 
1870 @samp{ls -l} on it produces output like:
1871
1872 @example
1873 -rwsr-xr-x   1 games    184422 Jul 30 15:17 caber-toss*
1874 @end example
1875
1876 @noindent
1877 The set-user-ID bit shows up in the file modes as the @samp{s}.
1878
1879 The scores file is given mode @code{644}, and doing an @samp{ls -l} on
1880 it shows:
1881
1882 @example
1883 -rw-r--r--  1 games           0 Jul 31 15:33 scores
1884 @end example
1885
1886 Here are the parts of the program that show how to set up the changed
1887 user ID.  This program is conditionalized so that it makes use of the
1888 saved IDs feature if it is supported, and otherwise uses @code{setreuid}
1889 to swap the effective and real user IDs.
1890
1891 @example
1892 #include <stdio.h>
1893 #include <sys/types.h>
1894 #include <unistd.h>
1895 #include <stdlib.h>
1896
1897
1898 /* @r{Save the effective and real UIDs.} */
1899
1900 uid_t euid, ruid;
1901
1902
1903 /* @r{Restore the effective UID to its original value.} */
1904
1905 void do_setuid (void)
1906 @{
1907   int status;
1908
1909 #ifdef _POSIX_SAVED_IDS
1910   status = setuid (euid);
1911 #else
1912   status = setreuid (ruid, euid);
1913 #endif
1914   if (status < 0) @{
1915     fprintf (stderr, "Couldn't set uid.\n");
1916     exit (status);
1917     @}
1918 @}
1919
1920
1921 /* @r{Set the effective UID to the real UID.} */
1922
1923 void undo_setuid (void)
1924 @{
1925   int status;
1926
1927 #ifdef _POSIX_SAVED_IDS
1928   status = setuid (ruid);
1929 #else
1930   status = setreuid (euid, ruid);
1931 #endif
1932   if (status < 0) @{
1933     fprintf (stderr, "Couldn't set uid.\n");
1934     exit (status);
1935     @}
1936 @}
1937
1938
1939 /* @r{Main program.} */
1940
1941 void main (void)
1942 @{
1943   /* @r{Save the real and effective user IDs.}  */
1944   ruid = getuid ();
1945   euid = geteuid ();
1946   undo_setuid ();
1947
1948   /* @r{Do the game and record the score.}  */
1949   @dots{}
1950 @}
1951 @end example
1952
1953 Notice how the first thing the @code{main} function does is to set the
1954 effective user ID back to the real user ID.  This is so that any other
1955 file accesses that are performed while the user is playing the game use
1956 the real user ID for determining permissions.  Only when the program
1957 needs to open the scores file does it switch back to the original
1958 effective user ID, like this:
1959
1960 @example
1961 /* @r{Record the score.} */
1962
1963 int record_score (int score)
1964 @{
1965   FILE *stream;
1966   char *myname;
1967
1968   /* @r{Open the scores file.} */
1969   do_setuid ();
1970   stream = fopen (SCORES_FILE, "a");
1971   undo_setuid ();
1972
1973   /* @r{Write the score to the file.} */
1974   if (stream) @{
1975     myname = cuserid (NULL);
1976     if (score < 0)
1977       fprintf (stream, "%10s: Couldn't lift the caber.\n", myname);
1978     else
1979       fprintf (stream, "%10s: %d feet.\n", myname, score);
1980     fclose (stream);
1981     return 0;
1982     @}
1983   else
1984     return -1;
1985 @}
1986 @end example
1987
1988 @node Tips for Setuid
1989 @subsection Tips for Writing Setuid Programs
1990
1991 It is easy for setuid programs to give the user access that isn't 
1992 intended--in fact, if you want to avoid this, you need to be careful.
1993 Here are some guidelines for preventing unintended access and
1994 minimizing its consequences when it does occur:
1995
1996 @itemize @bullet
1997 @item
1998 Don't have @code{setuid} programs owned by privileged accounts such as
1999 @samp{root} or @samp{superuser}, unless it is absolutely necessary.  If
2000 the resource is specific to your particular program, it's better to
2001 define a new, nonprivileged user ID or group ID just to manage that
2002 resource.
2003
2004 @item
2005 Be cautious about using the @code{system} and @code{exec} functions in
2006 combination with changing the effective user ID.  Don't let users of
2007 your program execute arbitrary programs under a changed user ID.
2008 Executing a shell is especially bad news.  Less obviously, the
2009 @code{execlp} and @code{execvp} functions are a potential risk (since
2010 the program they execute depends on the user's @code{PATH} environment
2011 variable).
2012
2013 If you must @code{exec} another program under a changed ID, specify
2014 an absolute file name (@pxref{File Name Resolution}) for the executable,
2015 and make sure that the protections on that executable and its directory
2016 are such that ordinary users cannot replace it with some other program.
2017
2018 @item
2019 Only use the user ID controlling the resource in the part of the program
2020 that actually uses that resource.  When you're finished with it, restore
2021 the effective user ID back to the actual user's user ID.
2022
2023 @item
2024 If the @code{setuid} part of your program needs to access other files
2025 besides the controlled resource, it should verify that the user would
2026 ordinarily have permission to access those files.  You can use the
2027 @code{access} function (@pxref{Access Permission}) to check this; it
2028 uses the real user and group IDs, rather than the effective IDs.
2029 @end itemize