Fix typos, dashes, @pxrefs, comments.
[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}.  These are assigned by
1505 the system administrator when the account is created in the system user
1506 database.  Normally, each login name in the database has a unique user
1507 ID, but it is possible for several login names to have the same
1508 user ID.
1509
1510 @cindex group name
1511 @cindex group ID
1512 The system administrator is also responsible for establishing which
1513 groups a user belongs to.  Users who are members of the same group can
1514 share resources (such as files) that are not accessible to users who are
1515 not a member of that group.  Each group has a @dfn{group name} and
1516 @dfn{group ID}.
1517
1518 When you log in to the computer, the processes that you create are
1519 assigned your user ID and your default group ID.
1520
1521 @cindex effective user ID
1522 @cindex real user ID
1523 A particular process actually has two user IDs associated with it.  The
1524 @dfn{real user ID} identifies the user who created the process.  The
1525 @dfn{effective user ID}, on the other hand, is used to determine
1526 permissions for accessing resources such as files.  Both the real and
1527 effective user ID can be changed during the lifetime of a process.
1528 @xref{Changing the User or Group ID}.
1529
1530 @cindex real group ID
1531 @cindex effective group ID
1532 @cindex supplementary group IDs
1533 Similarly, an individual process has both @dfn{real group ID} and
1534 @dfn{effective group ID} attributes.  In addition, since a user can
1535 belong to multiple groups, the additional groups that can affect
1536 access permissions are called @dfn{supplementary group IDs}.
1537
1538 For details on how a process's user IDs and group IDs affect its
1539 permission to access files, see @ref{Access Permission}.  For
1540 more information about the system user and group databases,
1541 see @ref{System Databases}.
1542
1543 The user ID of a process also controls permissions for sending signals
1544 using the @code{kill} function.  @xref{Signaling Another Process}.
1545
1546
1547
1548 @node Changing the User or Group ID
1549 @subsection Changing the User or Group ID
1550
1551 The most obvious situation where it is necessary for a process to change
1552 its user and/or group IDs is the @code{login} program.  It starts a
1553 shell and sets both the real and effective user and group IDs of to match
1554 those of the user who is logging in.
1555
1556 Some ordinary user programs need to use an effective user or group ID
1557 that corresponds to something other than the user who is actually
1558 running the program, too.  This permits the program to use a resource
1559 that wouldn't otherwise be accessible to the user who runs it.  This
1560 situation most commonly arises when you want to have a file that is
1561 controlled by your program but that shouldn't be read or modified
1562 directly by ordinary users, either because it implements some kind of
1563 locking protocol, or because you want to be careful to preserve the
1564 integrity or privacy of the information it contains.  This kind of
1565 restricted access can be implemented by having the program change its
1566 user or group ID to be the same as the owner of the resource.
1567
1568 As an example, some game programs use a file to keep track of high
1569 scores.  The game program itself obviously needs to be able to update
1570 this file no matter who is running it, but users shouldn't be allowed to
1571 write to the file directly---otherwise people might cheat and give
1572 themselves outrageously high scores!  The solution is to create a new
1573 user ID and login name (say, @samp{games}) to own the scores file, and
1574 make the file writable only by this user.  Then, when the game program
1575 wants to update this file, it can change its effective user ID to be
1576 that for @samp{games}.
1577
1578 @comment The example of phone bills was deleted by RMS because it endorses 
1579 @comment a way of running a computer facility that he detests.
1580
1581 @node Controlling Process Privileges
1582 @subsection Controlling Process Privileges
1583 @cindex restrictions on @code{setuid} programs
1584
1585 The ability to set the user ID of a process is very powerful facility
1586 and can be a source of unintentional privacy or security violations, or
1587 even intentional abuse by antisocial users.  Because of the potential
1588 for problems, there are a number of restrictions on how nonprivileged
1589 programs can use the facilities, and some guidelines you should follow
1590 in writing such programs.
1591
1592 You can't just arbitrarily set your user ID or group ID to anything you
1593 want; only privileged users can do that.  Permission for a program being
1594 run by an ordinary user to change to another user or group ID has to be
1595 granted explicitly by that user or group.  This is done by setting the
1596 modes on the executable file for the program in a special way.
1597
1598 When you execute a file (@pxref{Executing a File}) that has the
1599 set-user-ID mode bit set, then the effective user ID of the process is
1600 set to the owner of the file.  Likewise, if the set-group-ID mode bit of
1601 the file being executed is set, then the effective group ID of the
1602 process is set to the group owner of the file.  (Files that have these
1603 bits set are often referred to as @code{setuid} or @code{setgid}
1604 programs, respectively.)
1605
1606 @xref{File Attributes}, for a more general discussion of file modes and
1607 accessibility.
1608
1609 A process can always change its effective user (or group) ID back to its
1610 real ID.  This is often done because the program doesn't need the
1611 special privileges all the time.
1612
1613 @cindex saved IDs
1614 Many operating systems (including GNU) implement a feature known as
1615 @dfn{saved IDs}.  This means that the IDs of the owner and group owner
1616 of the executable file are remembered.  If the process changes its
1617 effective IDs back to its real user or group IDs, it can later change
1618 back to the saved IDs when it needs special privileges.
1619
1620 Other systems do not support saved IDs.  If you want to limit the parts
1621 of the program that have special privileges when it is running on one of
1622 these systems, the only way you can do this is by swapping the real and
1623 effective IDs, using @code{setreuid} or @code{setregid}.
1624
1625 Even with these restrictions, it is still possible for @code{setuid} or
1626 @code{setgid} programs to get into trouble.  There are a few
1627 things you can do in order to minimize the potential for problems in
1628 your own programs:
1629
1630 @itemize @bullet
1631 @item
1632 Don't have @code{setuid} programs owned by privileged accounts such as
1633 @samp{root} or @samp{superuser}, unless it is absolutely necessary.  If
1634 the resource is specific to your particular program, it's better to
1635 define a new, nonprivileged user ID just to manage that resource.
1636
1637 @item
1638 Be cautious about using the @code{system} and @code{exec} functions in
1639 combination with changing the effective user ID.  Don't let users of
1640 your program execute arbitrary programs under a changed user ID.
1641 Executing a shell is especially bad news.  Less obviously, the
1642 @code{execlp} and @code{execvp} functions are a potential risk (since
1643 the program they execute depends on the user's @code{PATH} environment
1644 variable).
1645
1646 If you must @code{exec} another program under a changed ID, specify
1647 an absolute file name (@pxref{File Name Resolution}) for the executable,
1648 and make sure that the protections on that executable and its directory
1649 are such that ordinary users cannot replace it with some other program.
1650
1651 @item
1652 Only use the user ID controlling the resource in the part of the program
1653 that actually uses that resource.  When you're finished with it, restore
1654 the effective user ID back to the user's real user ID.
1655
1656 @item
1657 If the @code{setuid} part of your program needs to access other files
1658 besides the controlled resource, it should verify that the user would
1659 ordinarily have permission to access those files.  You can use the
1660 @code{access} function (@pxref{Access Permission}) to check this; it
1661 uses the real user and group IDs, rather than the effective IDs.
1662 @end itemize
1663
1664
1665 @node User and Group ID Functions
1666 @subsection User and Group ID Functions
1667
1668 Here are detailed descriptions of the functions for inquiring about or
1669 changing the user and group IDs of a process.  To use these facilities,
1670 you must include the header files @file{sys/types.h} and
1671 @file{unistd.h}.
1672 @pindex unistd.h
1673 @pindex sys/types.h
1674
1675 @comment sys/types.h
1676 @comment POSIX.1
1677 @deftp {Data Type} uid_t
1678 This is an integer data type used to represent user IDs.  In the GNU
1679 library, this is equivalent to @code{unsigned short int}.
1680 @end deftp
1681
1682 @comment sys/types.h
1683 @comment POSIX.1
1684 @deftp {Data Type} gid_t
1685 This is an integer data type used to represent group IDs.  In the GNU
1686 library, this is equivalent to @code{unsigned short int}.
1687 @end deftp
1688
1689 @comment unistd.h
1690 @comment POSIX.1
1691 @deftypefun uid_t getuid ()
1692 The @code{getuid} function returns the real user ID of the process.
1693 @end deftypefun
1694
1695 @comment unistd.h
1696 @comment POSIX.1
1697 @deftypefun gid_t getgid ()
1698 The @code{getgid} function returns the real group ID of the process.
1699 @end deftypefun
1700
1701 @comment unistd.h
1702 @comment POSIX.1
1703 @deftypefun uid_t geteuid ()
1704 The @code{geteuid} function returns the effective user ID of the process.
1705 @end deftypefun
1706
1707 @comment unistd.h
1708 @comment POSIX.1
1709 @deftypefun gid_t getegid ()
1710 The @code{getegid} function returns the effective group ID of the process.
1711 @end deftypefun
1712
1713 @comment unistd.h
1714 @comment POSIX.1
1715 @deftypefun int getgroups (int @var{count}, gid_t *@var{groups})
1716 The @code{getgroups} function is used to inquire about the supplementary
1717 group IDs of the process.  Up to @var{count} of these group IDs are
1718 stored in the array @var{groups}; the return value from the function is
1719 the number of group IDs actually stored.  If @var{count} is smaller than
1720 the total number of supplementary group IDs, then @code{getgroups}
1721 returns a value of @code{-1} and @code{errno} is set to @code{EINVAL}.
1722
1723 If @var{count} is zero, then @code{getgroups} just returns the total
1724 number of supplementary group IDs.
1725
1726 Here's how to use @code{getgroups} to read all the supplementary group
1727 IDs:
1728
1729 @example
1730 @{
1731   int ngroups = getgroups (0, 0);
1732   gid_t *groups = (gid_t *) xmalloc (ngroups * sizeof (gid_t));
1733   int val = getgroups (ngroups, groups);
1734   if (val < 0)
1735
1736 The effective group ID of the process might or might not be included in
1737 the list of supplementary group IDs.
1738 @end example
1739 @end deftypefun
1740
1741 @comment unistd.h
1742 @comment POSIX.1
1743 @deftypefun int setuid (@var{newuid})
1744 This function sets both the real and effective user ID of the process
1745 to @var{newuid}, provided that the process has appropriate privileges.
1746
1747 If the process is not privileged, then @var{newuid} must either be equal
1748 to the real user ID or the saved user ID from the program's image file
1749 (but only if the implementation supports the @code{_POSIX_SAVED_IDS}
1750 feature).  In this case, @code{setuid} sets only the effective user ID
1751 and not the real user ID.
1752
1753 The @code{setuid} function returns a value of @code{0} to indicate
1754 successful completion, and a value of @code{-1} to indicate an error.
1755 The following @code{errno} error conditions are defined for this
1756 function:
1757
1758 @table @code
1759 @item EINVAL
1760 The value of the @var{newuid} argument is invalid.
1761
1762 @item EPERM
1763 The process does not have the appropriate privileges; you do not
1764 have permission to change to the specified ID.  @xref{Controlling Process
1765 Privileges}.
1766 @end table
1767 @end deftypefun
1768
1769 @comment unistd.h
1770 @comment BSD
1771 @deftypefun int setreuid (int @var{ruid}, int @var{euid})
1772 This function sets the real user ID of the process to @var{ruid} and
1773 the effective user ID to @var{euid}.
1774
1775 The @code{setreuid} function is provided for compatibility with 4.2 BSD
1776 Unix, which does not support saved IDs.  You can use this function to
1777 swap the effective and real user IDs of the process.  (Privileged users
1778 can make other changes as well.)  If saved IDs are supported, you should
1779 use that feature instead of this function.
1780
1781 The return value is @code{0} on success and @code{-1} on failure.
1782 The following @code{errno} error conditions are defined for this
1783 function:
1784
1785 @table @code
1786 @item EPERM
1787 The process does not have the appropriate privileges; you do not
1788 have permission to change to the specified ID.  @xref{Controlling Process
1789 Privileges}.
1790 @end table
1791 @end deftypefun
1792
1793 @comment unistd.h
1794 @comment POSIX.1
1795 @deftypefun int setgid (@var{newgid})
1796 This function sets both the real and effective group ID of the process
1797 to @var{newgid}, provided that the process has appropriate privileges.
1798
1799 If the process is not privileged, then @var{newgid} must either be equal
1800 to the real group ID or the saved group ID from the program's image
1801 file.  In this case, @code{setgid} sets only the effective group ID and
1802 not the real group ID.
1803
1804 The return values and error conditions for @code{setgid} are the same
1805 as those for @code{setuid}.
1806 @end deftypefun
1807
1808
1809 @comment unistd.h
1810 @comment BSD
1811 @deftypefun int setregid (int @var{rgid}, int @var{egid})
1812 This function sets the real group ID of the process to @var{rgid} and
1813 the effective group ID to @var{egid}.
1814
1815 The @code{setregid} function is provided for compatibility with 4.2 BSD
1816 Unix, which does not support saved IDs.  You can use this function to
1817 swap the effective and real group IDs of the process.  (Privileged users
1818 can make other changes.)  If saved IDs are supported, you should make use 
1819 of that feature instead of using this function.
1820
1821 The return values and error conditions for @code{setregid} are the same
1822 as those for @code{setreuid}.
1823 @end deftypefun
1824
1825 The GNU system also lets privileged processes change their supplementary 
1826 group IDs.  To use @code{setgroups} or @code{initgroups}, your programs
1827 should include the header file @file{grp.h}.
1828 @pindex grp.h
1829
1830 @comment grp.h
1831 @comment BSD
1832 @deftypefun int setgroups (size_t @var{count}, gid_t *@var{groups})
1833 This function sets the process's supplementary group IDs.  It can only
1834 be called from privileged processes.  The @var{count} argument specifies
1835 the number of group IDs in the array @var{groups}.
1836
1837 This function returns @code{0} if successful and @code{-1} on error.
1838 The following @code{errno} error conditions are defined for this
1839 function:
1840
1841 @table @code
1842 @item EPERM
1843 The calling process is not privileged.
1844 @end table
1845 @end deftypefun
1846
1847 @comment grp.h
1848 @comment BSD
1849 @deftypefun int initgroups (const char *@var{user}, gid_t @var{gid})
1850 The @code{initgroups} function effectively calls @code{setgroups} to
1851 set the process's supplementary group IDs to be the normal default for
1852 the user name @var{user}.  The group ID @var{gid} is also included.
1853 @end deftypefun
1854
1855 @node Setuid Program Example
1856 @subsection Setuid Program Example
1857
1858 Here's an example showing how to set up a program that changes its
1859 effective user ID.
1860
1861 This is part of a game program called @code{caber-toss} that
1862 manipulates a file @file{scores} that should be writable only by the game
1863 program itself.  The program assumes that its executable
1864 file will be installed with the set-user-ID bit set and owned by the
1865 same user as the @file{scores} file.  Typically, a system
1866 administrator will set up an account like @samp{games} for this purpose.
1867
1868 The executable file is given mode @code{4755}, so that doing an 
1869 @samp{ls -l} on it produces output like:
1870
1871 @example
1872 -rwsr-xr-x   1 games    184422 Jul 30 15:17 caber-toss*
1873 @end example
1874
1875 @noindent
1876 The set-user-ID bit shows up in the file modes as the @samp{s}.
1877
1878 The scores file is given mode @code{644}, and doing an @samp{ls -l} on
1879 it shows:
1880
1881 @example
1882 -rw-r--r--  1 games           0 Jul 31 15:33 scores
1883 @end example
1884
1885 Here are the parts of the program that show how to set up the changed
1886 user ID.  This program is conditionalized so that it makes use of the
1887 saved IDs feature if it is supported, and otherwise uses @code{setreuid}
1888 to swap the effective and real user IDs.
1889
1890 @example
1891 #include <stdio.h>
1892 #include <sys/types.h>
1893 #include <unistd.h>
1894 #include <stdlib.h>
1895
1896
1897 /* @r{Save the effective and real UIDs.} */
1898
1899 uid_t euid, ruid;
1900
1901
1902 /* @r{Restore the effective UID to its original value.} */
1903
1904 void do_setuid (void)
1905 @{
1906   int status;
1907
1908 #ifdef _POSIX_SAVED_IDS
1909   status = setuid (euid);
1910 #else
1911   status = setreuid (ruid, euid);
1912 #endif
1913   if (status < 0) @{
1914     fprintf (stderr, "Couldn't set uid.\n");
1915     exit (status);
1916     @}
1917 @}
1918
1919
1920 /* @r{Set the effective UID to the real UID.} */
1921
1922 void undo_setuid (void)
1923 @{
1924   int status;
1925
1926 #ifdef _POSIX_SAVED_IDS
1927   status = setuid (ruid);
1928 #else
1929   status = setreuid (euid, ruid);
1930 #endif
1931   if (status < 0) @{
1932     fprintf (stderr, "Couldn't set uid.\n");
1933     exit (status);
1934     @}
1935 @}
1936
1937
1938 /* @r{Main program.} */
1939
1940 void main (void)
1941 @{
1942   /* @r{Save the real and effective user IDs.}  */
1943   ruid = getuid ();
1944   euid = geteuid ();
1945   undo_setuid ();
1946
1947   /* @r{Do the game and record the score.}  */
1948   @dots{}
1949 @}
1950 @end example
1951
1952 Notice how the first thing the @code{main} function does is to set the
1953 effective user ID back to the real user ID.  This is so that any other
1954 file accesses that are performed while the user is playing the game use
1955 the real user ID for determining permissions.  Only when the program
1956 needs to open the scores file does it switch back to the original
1957 effective user ID, like this:
1958
1959 @example
1960 /* @r{Record the score.} */
1961
1962 int record_score (int score)
1963 @{
1964   FILE *stream;
1965   char *myname;
1966
1967   /* @r{Open the scores file.} */
1968   do_setuid ();
1969   stream = fopen (SCORES_FILE, "a");
1970   undo_setuid ();
1971
1972   /* @r{Write the score to the file.} */
1973   if (stream) @{
1974     myname = cuserid (NULL);
1975     if (score < 0)
1976       fprintf (stream, "%10s: Couldn't lift the caber.\n", myname);
1977     else
1978       fprintf (stream, "%10s: %d feet.\n", myname, score);
1979     fclose (stream);
1980     return 0;
1981     @}
1982   else
1983     return -1;
1984 @}
1985 @end example
1986