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