185d4d9038112ec18597ca1024880ba3cd2b10a6
[kopensolaris-gnu/glibc.git] / manual / startup.texi
1 @node Process Startup, Child Processes, Signal Handling, Top
2 @chapter Process Startup and Termination
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 This chapter explains what your program should do to handle the startup
13 of a process, to terminate its process, and to receive information
14 (arguments and the environment) from the parent process.
15
16 @menu
17 * Program Arguments::           Parsing the command-line arguments to
18                                  a program.
19 * Environment Variables::       How to access parameters inherited from
20                                  a parent process.
21 * Program Termination::         How to cause a process to terminate and
22                                  return status information to its parent.
23 @end menu
24
25 @node Program Arguments
26 @section Program Arguments
27 @cindex program arguments
28 @cindex command line arguments
29
30 @cindex @code{main} function
31 The system starts a C program by calling the function @code{main}.  It
32 is up to you to write a function named @code{main}---otherwise, you
33 won't even be able to link your program without errors.
34
35 You can define @code{main} either to take no arguments, or to take two
36 arguments that represent the command line arguments to the program, like
37 this:
38
39 @example
40 int main (int @var{argc}, char *@var{argv}[])
41 @end example
42
43 @cindex argc (program argument count)
44 @cindex argv (program argument vector)
45 The command line arguments are the whitespace-separated tokens given in
46 the shell command used to invoke the program; thus, in @samp{cat foo
47 bar}, the arguments are @samp{foo} and @samp{bar}.  The only way a
48 program can look at its command line arguments is via the arguments of
49 @code{main}.  If @code{main} doesn't take arguments, then you cannot get
50 at the command line.
51
52 The value of the @var{argc} argument is the number of command line
53 arguments.  The @var{argv} argument is a vector of C strings; its
54 elements are the individual command line argument strings.  The file
55 name of the program being run is also included in the vector as the
56 first element; the value of @var{argc} counts this element.  A null
57 pointer always follows the last element: @code{@var{argv}[@var{argc}]}
58 is this null pointer.
59
60 For the command @samp{cat foo bar}, @var{argc} is 3 and @var{argv} has
61 three elements, @code{"cat"}, @code{"foo"} and @code{"bar"}.
62
63 If the syntax for the command line arguments to your program is simple
64 enough, you can simply pick the arguments off from @var{argv} by hand.
65 But unless your program takes a fixed number of arguments, or all of the
66 arguments are interpreted in the same way (as file names, for example),
67 you are usually better off using @code{getopt} to do the parsing.
68
69 @menu
70 * Argument Syntax::       By convention, options start with a hyphen.
71 * Parsing Options::       The @code{getopt} function.
72 * Example of Getopt::     An example of parsing options with @code{getopt}.
73 * Long Options::          GNU suggests utilities accept long-named options.
74                            Here is how to do that.
75 * Long Option Example::   An example of using @code{getopt_long}.
76 @end menu
77
78 @node Argument Syntax
79 @subsection Program Argument Syntax Conventions
80 @cindex program argument syntax
81 @cindex syntax, for program arguments
82 @cindex command argument syntax
83
84 POSIX recommends these conventions for command line arguments.
85 @code{getopt} (@pxref{Parsing Options}) makes it easy to implement them.
86
87 @itemize @bullet
88 @item
89 Arguments are options if they begin with a hyphen delimiter (@samp{-}).
90
91 @item
92 Multiple options may follow a hyphen delimiter in a single token if
93 the options do not take arguments.  Thus, @samp{-abc} is equivalent to
94 @samp{-a -b -c}.
95
96 @item
97 Option names are single alphanumeric characters (as for @code{isalnum};
98 see @ref{Classification of Characters}).
99
100 @item
101 Certain options require an argument.  For example, the @samp{-o} command
102 of the @code{ld} command requires an argument---an output file name.
103
104 @item
105 An option and its argument may or may appear as separate tokens.  (In
106 other words, the whitespace separating them is optional.)  Thus,
107 @samp{-o foo} and @samp{-ofoo} are equivalent.
108
109 @item
110 Options typically precede other non-option arguments.
111
112 The implementation of @code{getopt} in the GNU C library normally makes
113 it appear as if all the option arguments were specified before all the
114 non-option arguments for the purposes of parsing, even if the user of
115 your program intermixed option and non-option arguments.  It does this
116 by reordering the elements of the @var{argv} array.  This behavior is
117 nonstandard; if you want to suppress it, define the
118 @code{_POSIX_OPTION_ORDER} environment variable.  @xref{Standard
119 Environment}.
120
121 @item
122 The argument @samp{--} terminates all options; any following arguments
123 are treated as non-option arguments, even if they begin with a hyphen.
124
125 @item
126 A token consisting of a single hyphen character is interpreted as an
127 ordinary non-option argument.  By convention, it is used to specify
128 input from or output to the standard input and output streams.
129
130 @item
131 Options may be supplied in any order, or appear multiple times.  The
132 interpretation is left up to the particular application program.
133 @end itemize
134
135 @cindex long-named options
136 GNU adds @dfn{long options} to these conventions.  Long options consist
137 of @samp{--} followed by a name made of alphanumeric characters.  Option
138 names are typically one to three words long, with hyphens to separate
139 words.  Users can abbreviate the option names as long as the
140 abbreviations are unique.
141
142 To specify an argument for a long option, write
143 @samp{--@var{name}=@var{value}}.  This syntax enables a long option to
144 accept an argument that is itself optional.
145
146 Eventually, the GNU system will provide completion for long option names
147 in the shell.
148
149 @node Parsing Options
150 @subsection Parsing Program Options
151 @cindex program arguments, parsing
152 @cindex command arguments, parsing
153 @cindex parsing program arguments
154
155 Here are the details about how to call the @code{getopt} function.  To
156 use this facility, your program must include the header file
157 @file{unistd.h}.
158 @pindex unistd.h
159
160 @comment unistd.h
161 @comment POSIX.2
162 @deftypevar int opterr
163 If the value of this variable is nonzero, then @code{getopt} prints an
164 error message to the standard error stream if it encounters an unknown
165 option character or an option with a missing required argument.  This is
166 the default behavior.  If you set this variable to zero, @code{getopt}
167 does not print any messages, but it still returns @code{?} to indicate
168 an error.
169 @end deftypevar
170
171 @comment unistd.h
172 @comment POSIX.2
173 @deftypevar int optopt
174 When @code{getopt} encounters an unknown option character or an option
175 with a missing required argument, it stores that option character in
176 this variable.  You can use this for providing your own diagnostic
177 messages.
178 @end deftypevar
179
180 @comment unistd.h
181 @comment POSIX.2
182 @deftypevar int optind
183 This variable is set by @code{getopt} to the index of the next element
184 of the @var{argv} array to be processed.  Once @code{getopt} has found
185 all of the option arguments, you can use this variable to determine
186 where the remaining non-option arguments begin.  The initial value of
187 this variable is @code{1}.
188 @end deftypevar
189
190 @comment unistd.h
191 @comment POSIX.2
192 @deftypevar {char *} optarg
193 This variable is set by @code{getopt} to point at the value of the
194 option argument, for those options that accept arguments.
195 @end deftypevar
196
197 @comment unistd.h
198 @comment POSIX.2
199 @deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options})
200 The @code{getopt} function gets the next option argument from the
201 argument list specified by the @var{argv} and @var{argc} arguments.
202 Normally these values come directly from the arguments received by
203 @code{main}.
204
205 The @var{options} argument is a string that specifies the option
206 characters that are valid for this program.  An option character in this
207 string can be followed by a colon (@samp{:}) to indicate that it takes a
208 required argument.
209
210 If the @var{options} argument string begins with a hyphen (@samp{-}), this
211 is treated specially.  It permits arguments without an option to be
212 returned as if they were associated with option character @samp{\0}.
213
214 The @code{getopt} function returns the option character for the next
215 command line option.  When no more option arguments are available, it
216 returns @code{-1}.  There may still be more non-option arguments; you
217 must compare the external variable @code{optind} against the @var{argv}
218 parameter to check this.
219
220 If the options has an argument, @code{getopt} returns the argument by
221 storing it in the varables @var{optarg}.  You don't ordinarily need to
222 copy the @code{optarg} string, since it is a pointer into the original
223 @var{argv} array, not into a static area that might be overwritten.
224
225 If @code{getopt} finds an option character in @var{argv} that was not
226 included in @var{options}, or a missing option argument, it returns
227 @samp{?} and sets the external variable @code{optopt} to the actual
228 option character.  In addition, if the external variable @code{opterr}
229 is nonzero, @code{getopt} prints an error message.
230 @end deftypefun
231
232 @node Example of Getopt
233 @subsection Example of Parsing Arguments with @code{getopt}
234
235 Here is an example showing how @code{getopt} is typically used.  The
236 key points to notice are:
237
238 @itemize @bullet
239 @item
240 Normally, @code{getopt} is called in a loop.  When @code{getopt} returns
241 @code{-1}, indicating no more options are present, the loop terminates.
242
243 @item
244 A @code{switch} statement is used to dispatch on the return value from
245 @code{getopt}.  In typical use, each case just sets a variable that
246 is used later in the program.
247
248 @item
249 A second loop is used to process the remaining non-option arguments.
250 @end itemize
251
252 @example
253 @include testopt.c.texi
254 @end example
255
256 Here are some examples showing what this program prints with different
257 combinations of arguments:
258
259 @example
260 % testopt
261 aflag = 0, bflag = 0, cvalue = (null)
262
263 % testopt -a -b
264 aflag = 1, bflag = 1, cvalue = (null)
265
266 % testopt -ab
267 aflag = 1, bflag = 1, cvalue = (null)
268
269 % testopt -c foo
270 aflag = 0, bflag = 0, cvalue = foo
271
272 % testopt -cfoo
273 aflag = 0, bflag = 0, cvalue = foo
274
275 % testopt arg1
276 aflag = 0, bflag = 0, cvalue = (null)
277 Non-option argument arg1
278
279 % testopt -a arg1
280 aflag = 1, bflag = 0, cvalue = (null)
281 Non-option argument arg1
282
283 % testopt -c foo arg1
284 aflag = 0, bflag = 0, cvalue = foo
285 Non-option argument arg1
286
287 % testopt -a -- -b
288 aflag = 1, bflag = 0, cvalue = (null)
289 Non-option argument -b
290
291 % testopt -a -
292 aflag = 1, bflag = 0, cvalue = (null)
293 Non-option argument -
294 @end example
295
296 @node Long Options
297 @subsection Parsing Long Options
298
299 To accept GNU-style long options as well as single-character options,
300 use the function @code{getopt_long} instead of @code{getopt}.  You
301 should do this in every program that uses options, for it takes little
302 extra work and helps beginners remember how to use the program.
303
304 @comment getopt.h
305 @comment GNU
306 @deftp {Data Type} {struct option}
307 This structure describes a single long option name for the sake of
308 @code{getopt_long}.  The argument @var{longopts} must be an array of
309 these structures, one for each long option.  Terminate the array with an
310 element containing all zeros.
311
312 The @code{struct option} structure has these fields:
313
314 @table @code
315 @item name
316 This field is the name of the option.  It is a string.
317
318 @item has_arg
319 This field says whether the option takes an argument.  It is an integer,
320 and there are three legitimate values: @code{no_argument},
321 @code{required_argument} and @code{optional_argument}.
322
323 @item flag
324 @itemx val
325 These fields control how to report or act on the option when it occurs.
326
327 If @code{flag} is zero, then the @code{val} is a value which identifies
328 this option.  Often these values are chosen to uniquely identify
329 particular long options.
330
331 If @code{flag} is nonzero, it should be the address of an @code{int}
332 variable which is the flag for this option.  The value in @code{val} is
333 the value to store in the flag to indicate that the option was seen.
334 @end table
335 @end deftp
336
337 @comment getopt.h
338 @comment GNU
339 @deftypefun getopt_long (int @var{argc}, char **@var{argv}, const char *@var{short}, struct option *@var{long}, int *@var{indexptr})
340 Decode options from the vector @var{argv} (whose length is @var{argc}).
341 The argument @var{short} describes the short options to accept, just as
342 it does in @code{getopt}.  The argument @var{long} describes the long
343 options to accept (see above).
344
345 When @code{getopt_long} encounters a short option, it does the same
346 thing that @code{getopt} would do: it returns the character code for the
347 option, and stores the options argument (if it has one) in @code{optarg}.
348
349 When @code{getopt_long} encounters a long option, it takes actions based
350 on the @code{flag} and @code{val} fields of the definition of that
351 option.
352
353 If @code{flag} is zero, then @code{getopt_long} returns the contents of
354 @code{val} to indicate which option it found.  You should arrange
355 distinct values in the @code{val} field for options with different
356 meanings, so you can decode these values after @code{getopt_long}
357 returns.  If the long option is equivalent to a short option, you can
358 use the short option's character code in @code{val}.
359
360 If @code{flag} is nonzero, that means this option should just set a flag
361 in the program.  The flag is a variable of type @code{int} that you
362 define.  Put the address of the flag in the @code{flag} field.  Put in
363 the @code{val} field the value you would like this option to store in
364 the flag.  In this case, @code{getopt_long} returns @code{0}.
365
366 For any long option, @code{getopt_long} tells you the index in the array
367 @var{long} of the options definition, by storing it into
368 @code{*@var{indexptr}}.  You can get the name of the option with
369 @code{@var{long}[*@var{indexptr}].name}.  So you can distinguish among
370 long options either by the values in their @code{val} fields or by their
371 indices.  You can also distinguish in this way among long options that
372 set flags.
373
374 When a long option has an argument, @code{getopt_long} puts the argument
375 value in the variable @code{optarg} before returning.  When the option
376 has no argument, the value in @code{optarg} is @code{0}.  This is how
377 you can tell whether an optional argument was supplied.
378
379 When @code{getopt_long} has no more options to handle, it returns
380 @code{-1}, and leaves in the variable @code{optind} the index in
381 @var{argv} of the next remaining argument.
382 @end deftypefun
383
384 @node Long Option Example
385 @subsection Example of Parsing Long Options
386
387 @example
388 @include longopt.c.texi
389 @end example
390
391 @node Environment Variables
392 @section Environment Variables
393
394 @cindex environment variable
395 When a program is executed, it receives information about the context in
396 which it was invoked in two ways.  The first mechanism uses the
397 @var{argv} and @var{argc} arguments to its @code{main} function, and is
398 discussed in @ref{Program Arguments}.  The second mechanism is
399 uses @dfn{environment variables} and is discussed in this section.
400
401 The @var{argv} mechanism is typically used to pass command-line
402 arguments specific to the particular program being invoked.  The
403 environment, on the other hand, keeps track of information that is
404 shared by many programs, changes infrequently, and that is less
405 frequently accessed.
406
407 The environment variables discussed in this section are the same
408 environment variables that you set using assignments and the
409 @code{export} command in the shell.  Programs executed from the shell
410 inherit all of the environment variables from the shell.
411
412 @cindex environment
413 Standard environment variables are used for information about the user's
414 home directory, terminal type, current locale, and so on; you can define
415 additional variables for other purposes.  The set of all environment
416 variables that have values is collectively known as the
417 @dfn{environment}.
418
419 Names of environment variables are case-sensitive and must not contain
420 the character @samp{=}.  System-defined environment variables are
421 invariably uppercase.
422
423 The values of environment variables can be anything that can be
424 represented as a string.  A value must not contain an embedded null
425 character, since this is assumed to terminate the string.
426
427
428 @menu
429 * Environment Access::    How to get and set the values of
430                            environment variables.
431 * Standard Environment::  These environment variables have
432                            standard interpretations.
433 @end menu
434
435 @node Environment Access
436 @subsection Environment Access
437 @cindex environment access
438 @cindex environment representation
439
440 The value of an environment variable can be accessed with the
441 @code{getenv} function.  This is declared in the header file
442 @file{stdlib.h}.
443 @pindex stdlib.h
444
445 @comment stdlib.h
446 @comment ANSI
447 @deftypefun {char *} getenv (const char *@var{name})
448 This function returns a string that is the value of the environment
449 variable @var{name}.  You must not modify this string.  In some systems
450 not using the GNU library, it might be overwritten by subsequent calls
451 to @code{getenv} (but not by any other library function).  If the
452 environment variable @var{name} is not defined, the value is a null
453 pointer.
454 @end deftypefun
455
456
457 @comment stdlib.h
458 @comment SVID
459 @deftypefun int putenv (const char *@var{string})
460 The @code{putenv} function adds or removes definitions from the environment.
461 If the @var{string} is of the form @samp{@var{name}=@var{value}}, the
462 definition is added to the environment.  Otherwise, the @var{string} is
463 interpreted as the name of an environment variable, and any definition
464 for this variable in the environment is removed.
465
466 The GNU library provides this function for compatibility with SVID; it
467 may not be available in other systems.
468 @end deftypefun
469
470 You can deal directly with the underlying representation of environment
471 objects to add more variables to the environment (for example, to
472 communicate with another program you are about to execute; see
473 @ref{Executing a File}).  
474
475 @comment unistd.h
476 @comment POSIX.1
477 @deftypevar {char **} environ
478 The environment is represented as an array of strings.  Each string is
479 of the format @samp{@var{name}=@var{value}}.  The order in which
480 strings appear in the environment is not significant, but the same
481 @var{name} must not appear more than once.  The last element of the
482 array is a null pointer.
483
484 This variable is not declared in any header file, but if you declare it
485 in your own program as @code{extern}, the right thing will happen.
486
487 If you just want to get the value of an environment variable, use
488 @code{getenv}.
489 @end deftypevar
490
491 @node Standard Environment
492 @subsection Standard Environment Variables
493 @cindex standard environment variables
494
495 These environment variables have standard meanings.  This doesn't mean
496 that they are always present in the environment; but if these variables
497 @emph{are} present, they have these meanings, and that you shouldn't try
498 to use these environment variable names for some other purpose.
499
500 @table @code
501 @item HOME
502 @cindex HOME environment variable
503 @cindex home directory
504 This is a string representing the user's @dfn{home directory}, or
505 initial default working directory.
506
507 The user can set @code{HOME} to any value.
508 If you need to make sure to obtain the proper home directory
509 for a particular user, you should not use @code{HOME}; instead,
510 look up the user's name in the user database (@pxref{User Database}).
511
512 For most purposes, it is better to use @code{HOME}, precisely because
513 this lets the user specify the value.
514
515 @item LOGNAME
516 @cindex LOGNAME environment variable
517 This is the name that the user used to log in.  Since the value in the
518 environment can be tweaked arbitrarily, this is not a reliable way to
519 identify the user who is running a process; a function like
520 @code{getlogin} (@pxref{User Identification Functions}) is better for
521 that purpose.
522
523 For most purposes, it is better to use @code{LOGNAME}, precisely because
524 this lets the user specify the value.
525
526 @item PATH
527 @cindex PATH environment variable
528 A @dfn{path} is a sequence of directory names which is used for
529 searching for a file.  The variable @var{PATH} holds a path used
530 for searching for programs to be run.
531
532 The @code{execlp} and @code{execvp} functions (@pxref{Executing a File})
533 use this environment variable, as do many shells and other utilities
534 which are implemented in terms of those functions.
535
536 The syntax of a path is a sequence of directory names separated by
537 colons.  An empty string instead of a directory name stands for the 
538 current directory (@pxref{Working Directory}).
539
540 A typical value for this environment variable might be a string like:
541
542 @example
543 .:/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local:/usr/local/bin
544 @end example
545
546 This means that if the user tries to execute a program named @code{foo},
547 the system will look for files named @file{./foo}, @file{/bin/foo},
548 @file{/etc/foo}, and so on.  The first of these files that exists is
549 the one that is executed.
550
551 @item TERM
552 @cindex TERM environment variable
553 This specifies the kind of terminal that is receiving program output.
554 Some programs can make use of this information to take advantage of
555 special escape sequences or terminal modes supported by particular kinds
556 of terminals.  Many programs which use the termcap library
557 (@pxref{Finding a Terminal Description,Find,,termcap,The Termcap Library
558 Manual}) use the @code{TERM} environment variable, for example.
559
560 @item TZ
561 @cindex TZ environment variable
562 This specifies the time zone.  @xref{Time Zone}, for information about
563 the format of this string and how it is used.
564
565 @item LANG
566 @cindex LANG environment variable
567 This specifies the default locale to use for attribute categories where
568 neither @code{LC_ALL} nor the specific environment variable for that
569 category is set.  @xref{Locales}, for more information about
570 locales.
571
572 @ignore
573 @c I doubt this really exists
574 @item LC_ALL
575 @cindex LC_ALL environment variable
576 This is similar to the @code{LANG} environment variable.  However, its
577 value takes precedence over any values provided for the individual
578 attribute category environment variables, or for the @code{LANG}
579 environment variable.
580 @end ignore
581
582 @item LC_COLLATE
583 @cindex LC_COLLATE environment variable
584 This specifies what locale to use for string sorting.
585
586 @item LC_CTYPE
587 @cindex LC_CTYPE environment variable
588 This specifies what locale to use for character sets and character
589 classification.
590
591 @item LC_MONETARY
592 @cindex LC_MONETARY environment variable
593 This specifies what locale to use for formatting monetary values.
594
595 @item LC_NUMERIC
596 @cindex LC_NUMERIC environment variable
597 This specifies what locale to use for formatting numbers.
598
599 @item LC_TIME
600 @cindex LC_TIME environment variable
601 This specifies what locale to use for formatting date/time values.
602
603 @item _POSIX_OPTION_ORDER
604 @cindex _POSIX_OPTION_ORDER environment variable.
605 If this environment variable is defined, it suppresses the usual
606 reordering of command line arguments by @code{getopt}.  @xref{Argument Syntax}.
607 @end table
608
609 @node Program Termination
610 @section Program Termination
611 @cindex program termination
612 @cindex process termination
613
614 @cindex exit status value
615 The usual way for a program to terminate is simply for its @code{main}
616 function to return.  The @dfn{exit status value} returned from the
617 @code{main} function is used to report information back to the process's
618 parent process or shell.
619
620 A program can also terminate normally by calling the @code{exit}
621 function.
622
623 In addition, programs can be terminated by signals; this is discussed in
624 more detail in @ref{Signal Handling}.  The @code{abort} function causes
625 a signal that kills the program.
626
627 @menu
628 * Normal Termination::          If a program calls @code{exit}, a
629                                  process terminates normally.
630 * Exit Status::                 The @code{exit status} provides information 
631                                  about why the process terminated. 
632 * Cleanups on Exit::            A process can run its own cleanup
633                                  functions upon normal termination. 
634 * Aborting a Program::          The @code{abort} function causes
635                                  abnormal program termination. 
636 * Termination Internals::       What happens when a process terminates.
637 @end menu
638
639 @node Normal Termination
640 @subsection Normal Termination
641
642 A process terminates normally when the program calls @code{exit}.
643 Returning from @code{main} is equivalent to calling @code{exit}, and
644 the value that @code{main} returns is used as the argument to @code{exit}.
645
646 @comment stdlib.h
647 @comment ANSI
648 @deftypefun void exit (int @var{status})
649 The @code{exit} function terminates the process with status
650 @var{status}.  This function does not return.
651 @end deftypefun
652
653 Normal termination causes the following actions:
654
655 @enumerate
656 @item 
657 Functions that were registered with the @code{atexit} or @code{on_exit}
658 functions are called in the reverse order of their registration.  This
659 mechanism allows your application to specify its own ``cleanup'' actions
660 to be performed at program termination.  Typically, this is used to do
661 things like saving program state information in a file, or unlocking
662 locks in shared data bases.
663
664 @item 
665 All open streams are closed, writing out any buffered output data.  See
666 @ref{Opening and Closing Streams}.  In addition, temporary files opened
667 with the @code{tmpfile} function are removed; see @ref{Temporary Files}.
668
669 @item 
670 @code{_exit} is called.  @xref{Termination Internals}.
671 @end enumerate
672
673 @node Exit Status
674 @subsection Exit Status
675 @cindex exit status
676
677 When a program exits, it can return to the parent process a small
678 amount of information about the cause of termination, using the
679 @dfn{exit status}.  This is a value between 0 and 255 that the exiting
680 process passes as an argument to @code{exit}.
681
682 Normally you should use the exit status to report very broad information
683 about success or failure.  You can't provide a lot of detail about the
684 reasons for the failure, and most parent processes would not want much
685 detail anyway.
686
687 There are conventions for what sorts of status values certain programs
688 should return.  The most common convention is simply 0 for success and 1
689 for failure.  Programs that perform comparison use a different
690 convention: they use status 1 to indicate a mismatch, and status 2 to
691 indicate an inability to compare.  Your program should follow an
692 existing convention if an existing convention makes sense for it.
693
694 A general convention reserves status values 128 and up for special
695 purposes.  In particular, the value 128 is used to indicate failure to
696 execute another program in a subprocess.  This convention is not
697 universally obeyed, but it is a good idea to follow it in your programs.
698
699 @strong{Warning:} Don't try to use the number of errors as the exit
700 status.  This is actually not very useful; a parent process would
701 generally not care how many errors occurred.  Worse than that, it does
702 not work, because the status value is truncated to eight bits.
703 Thus, if the program tried to report 256 errors, the parent would
704 receive a report of 0 errors---that is, success.
705
706 For the same reason, it does not work to use the value of @code{errno}
707 as the exit status---these can exceed 255.
708
709 @strong{Portability note:} Some non-POSIX systems use different
710 conventions for exit status values.  For greater portability, you can
711 use the macros @code{EXIT_SUCCESS} and @code{EXIT_FAILURE} for the
712 conventional status value for success and failure, respectively.  They
713 are declared in the file @file{stdlib.h}.
714 @pindex stdlib.h
715
716 @comment stdlib.h
717 @comment ANSI
718 @deftypevr Macro int EXIT_SUCCESS
719 This macro can be used with the @code{exit} function to indicate
720 successful program completion.
721
722 On POSIX systems, the value of this macro is @code{0}.  On other
723 systems, the value might be some other (possibly non-constant) integer
724 expression.
725 @end deftypevr
726
727 @comment stdlib.h
728 @comment ANSI
729 @deftypevr Macro int EXIT_FAILURE
730 This macro can be used with the @code{exit} function to indicate
731 unsuccessful program completion in a general sense.
732
733 On POSIX systems, the value of this macro is @code{1}.  On other
734 systems, the value might be some other (possibly non-constant) integer
735 expression.  Other nonzero status values also indicate future.  Certain
736 programs use different nonzero status values to indicate particular
737 kinds of "non-success".  For example, @code{diff} uses status value
738 @code{1} to mean that the files are different, and @code{2} or more to
739 mean that there was difficulty in opening the files.
740 @end deftypevr
741
742 @node Cleanups on Exit
743 @subsection Cleanups on Exit
744
745 Your program can arrange to run its own cleanup functions if normal
746 termination happens.  If you are writing a library for use in various
747 application programs, then it is unreliable to insist that all
748 applications call the library's cleanup functions explicitly before
749 exiting.  It is much more robust to make the cleanup invisible to the
750 application, by setting up a cleanup function in the library itself
751 using @code{atexit} or @code{on_exit}.
752
753 @comment stdlib.h
754 @comment ANSI
755 @deftypefun int atexit (void (*@var{function}) ())
756 The @code{atexit} function registers the function @var{function} to be
757 called at normal program termination.  The @var{function} is called with
758 no arguments.
759
760 The return value from @code{atexit} is zero on success and nonzero if
761 the function cannot be registered. 
762 @end deftypefun
763
764 @comment stdlib.h
765 @comment SunOS
766 @deftypefun int on_exit (void (*@var{function})(int @var{status}, void *@var{arg}), void *@var{arg})
767 This function is a somewhat more powerful variant of @code{atexit}.  It
768 accepts two arguments, a function @var{function} and an arbitrary
769 pointer @var{arg}.  At normal program termination, the @var{function} is
770 called with two arguments:  the @var{status} value passed to @code{exit},
771 and the @var{arg}.
772
773 This function is included in the GNU C library only for compatibility
774 for SunOS, and may not be supported by other implementations.
775 @end deftypefun
776
777 Here's a trivial program that illustrates the use of @code{exit} and
778 @code{atexit}:
779
780 @example
781 #include <stdio.h>
782 #include <stdlib.h>
783
784 void
785 bye ()
786 @{
787   printf ("Goodbye, cruel world....\n");
788 @}
789
790 void
791 main ()
792 @{
793   atexit (bye);
794   exit (EXIT_SUCCESS);
795 @}
796 @end example
797
798 @noindent
799 When this program is executed, it just prints the message and exits.
800
801 @node Aborting a Program
802 @subsection Aborting a Program
803 @cindex aborting a program
804
805 You can abort your program using the @code{abort} function.  The prototype
806 for this function is in @file{stdlib.h}.
807 @pindex stdlib.h
808
809 @comment stdlib.h
810 @comment ANSI
811 @deftypefun void abort ()
812 The @code{abort} function causes abnormal program termination.  This
813 does not execute cleanup functions registered with @code{atexit} or
814 @code{on_exit}.
815
816 This function actually terminates the process by raising a
817 @code{SIGABRT} signal, and your program can include a handler to
818 intercept this signal; see @ref{Signal Handling}.
819
820 @strong{Incomplete:}  Why would you want to define such a handler?
821 @end deftypefun
822
823 @c rms: I put this in.
824 @strong{Future Change Warning:} Proposed Federal censorship regulations
825 may prohibit us us from giving you information about the possibility of
826 calling this function.  We would be required to say that this is not an
827 acceptable way of terminating a program.
828
829 @node Termination Internals
830 @subsection Termination Internals
831
832 The @code{_exit} function is the primitive used for process termination
833 by @code{exit}.  It is declared in the header file @file{unistd.h}.
834 @pindex unistd.h
835
836 @comment unistd.h
837 @comment POSIX.1
838 @deftypefun void _exit (int @var{status})
839 The @code{_exit} function is the primitive for causing a process to
840 terminate with status @var{status}.  Calling this function does not
841 execute cleanup functions registered with @code{atexit} or
842 @code{on_exit}.
843 @end deftypefun
844
845 When a process terminates for any reason---either by an explicit
846 termination call, or termination as a result of a signal---the
847 following things happen:
848
849 @itemize @bullet
850 @item
851 All open file descriptors in the process are closed.  @xref{Low-Level
852 Input/Output}.
853
854 @item
855 The low-order 8 bits of the return status code are saved to be reported
856 back to the parent process via @code{wait} or @code{waitpid}; see
857 @ref{Process Completion}.
858
859 @item
860 Any child processes of the process being terminated are assigned a new
861 parent process.  (This is the @code{init} process, with process ID 1.)
862
863 @item
864 A @code{SIGCHLD} signal is sent to the parent process.
865
866 @item
867 If the process is a session leader that has a controlling terminal, then
868 a @code{SIGHUP} signal is sent to each process in the foreground job,
869 and the controlling terminal is disassociated from that session.
870 @xref{Job Control}.
871
872 @item
873 If termination of a process causes a process group to become orphaned,
874 and any member of that process group is stopped, then a @code{SIGHUP}
875 signal and a @code{SIGCONT} signal are sent to each process in the
876 group.  @xref{Job Control}.
877 @end itemize