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