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