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