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