(Tools for Compilation): Grammar fixes.
[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.  The same applies of course to
344 dynamically allocated variables which are freed later.
345
346 This function is part of the extended Unix interface.  Since it was also
347 available in old SVID libraries you should define either
348 @var{_XOPEN_SOURCE} or @var{_SVID_SOURCE} before including any header.
349 @end deftypefun
350
351
352 @comment stdlib.h
353 @comment BSD
354 @deftypefun int setenv (const char *@var{name}, const char *@var{value}, int @var{replace})
355 The @code{setenv} function can be used to add a new definition to the
356 environment.  The entry with the name @var{name} is replaced by the
357 value @samp{@var{name}=@var{value}}.  Please note that this is also true
358 if @var{value} is the empty string.  To do this a new string is created
359 and the strings @var{name} and @var{value} are copied.  A null pointer
360 for the @var{value} parameter is illegal.  If the environment already
361 contains an entry with key @var{name} the @var{replace} parameter
362 controls the action.  If replace is zero, nothing happens.  Otherwise
363 the old entry is replaced by the new one.
364
365 Please note that you cannot remove an entry completely using this function.
366
367 This function was originally part of the BSD library but is now part of
368 the Unix standard.
369 @end deftypefun
370
371 @comment stdlib.h
372 @comment BSD
373 @deftypefun int 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 The function return @code{-1} if @var{name} is a null pointer, points to
381 an empty string, or points to a string containing a @code{=} character.
382 It returns @code{0} if the call succeeded.
383
384 This function was originally part of the BSD library but is now part of
385 the Unix standard.  The BSD version had no return value, though.
386 @end deftypefun
387
388 There is one more function to modify the whole environment.  This
389 function is said to be used in the POSIX.9 (POSIX bindings for Fortran
390 77) and so one should expect it did made it into POSIX.1.  But this
391 never happened.  But we still provide this function as a GNU extension
392 to enable writing standard compliant Fortran environments.
393
394 @comment stdlib.h
395 @comment GNU
396 @deftypefun int clearenv (void)
397 The @code{clearenv} function removes all entries from the environment.
398 Using @code{putenv} and @code{setenv} new entries can be added again
399 later.
400
401 If the function is successful it returns @code{0}.  Otherwise the return
402 value is nonzero.
403 @end deftypefun
404
405
406 You can deal directly with the underlying representation of environment
407 objects to add more variables to the environment (for example, to
408 communicate with another program you are about to execute;
409 @pxref{Executing a File}).
410
411 @comment unistd.h
412 @comment POSIX.1
413 @deftypevar {char **} environ
414 The environment is represented as an array of strings.  Each string is
415 of the format @samp{@var{name}=@var{value}}.  The order in which
416 strings appear in the environment is not significant, but the same
417 @var{name} must not appear more than once.  The last element of the
418 array is a null pointer.
419
420 This variable is declared in the header file @file{unistd.h}.
421
422 If you just want to get the value of an environment variable, use
423 @code{getenv}.
424 @end deftypevar
425
426 Unix systems, and the GNU system, pass the initial value of
427 @code{environ} as the third argument to @code{main}.
428 @xref{Program Arguments}.
429
430 @node Standard Environment
431 @subsection Standard Environment Variables
432 @cindex standard environment variables
433
434 These environment variables have standard meanings.  This doesn't mean
435 that they are always present in the environment; but if these variables
436 @emph{are} present, they have these meanings.  You shouldn't try to use
437 these environment variable names for some other purpose.
438
439 @comment Extra blank lines make it look better.
440 @table @code
441 @item HOME
442 @cindex @code{HOME} environment variable
443 @cindex home directory
444
445 This is a string representing the user's @dfn{home directory}, or
446 initial default working directory.
447
448 The user can set @code{HOME} to any value.
449 If you need to make sure to obtain the proper home directory
450 for a particular user, you should not use @code{HOME}; instead,
451 look up the user's name in the user database (@pxref{User Database}).
452
453 For most purposes, it is better to use @code{HOME}, precisely because
454 this lets the user specify the value.
455
456 @c !!! also USER
457 @item LOGNAME
458 @cindex @code{LOGNAME} environment variable
459
460 This is the name that the user used to log in.  Since the value in the
461 environment can be tweaked arbitrarily, this is not a reliable way to
462 identify the user who is running a program; a function like
463 @code{getlogin} (@pxref{Who Logged In}) is better for that purpose.
464
465 For most purposes, it is better to use @code{LOGNAME}, precisely because
466 this lets the user specify the value.
467
468 @item PATH
469 @cindex @code{PATH} environment variable
470
471 A @dfn{path} is a sequence of directory names which is used for
472 searching for a file.  The variable @code{PATH} holds a path used
473 for searching for programs to be run.
474
475 The @code{execlp} and @code{execvp} functions (@pxref{Executing a File})
476 use this environment variable, as do many shells and other utilities
477 which are implemented in terms of those functions.
478
479 The syntax of a path is a sequence of directory names separated by
480 colons.  An empty string instead of a directory name stands for the
481 current directory (@pxref{Working Directory}).
482
483 A typical value for this environment variable might be a string like:
484
485 @smallexample
486 :/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local/bin
487 @end smallexample
488
489 This means that if the user tries to execute a program named @code{foo},
490 the system will look for files named @file{foo}, @file{/bin/foo},
491 @file{/etc/foo}, and so on.  The first of these files that exists is
492 the one that is executed.
493
494 @c !!! also TERMCAP
495 @item TERM
496 @cindex @code{TERM} environment variable
497
498 This specifies the kind of terminal that is receiving program output.
499 Some programs can make use of this information to take advantage of
500 special escape sequences or terminal modes supported by particular kinds
501 of terminals.  Many programs which use the termcap library
502 (@pxref{Finding a Terminal Description,Find,,termcap,The Termcap Library
503 Manual}) use the @code{TERM} environment variable, for example.
504
505 @item TZ
506 @cindex @code{TZ} environment variable
507
508 This specifies the time zone.  @xref{TZ Variable}, for information about
509 the format of this string and how it is used.
510
511 @item LANG
512 @cindex @code{LANG} environment variable
513
514 This specifies the default locale to use for attribute categories where
515 neither @code{LC_ALL} nor the specific environment variable for that
516 category is set.  @xref{Locales}, for more information about
517 locales.
518
519 @ignore
520 @c I doubt this really exists
521 @item LC_ALL
522 @cindex @code{LC_ALL} environment variable
523
524 This is similar to the @code{LANG} environment variable.  However, its
525 value takes precedence over any values provided for the individual
526 attribute category environment variables, or for the @code{LANG}
527 environment variable.
528 @end ignore
529
530 @item LC_ALL
531 @cindex @code{LC_ALL} environment variable
532
533 If this environment variable is set it overrides the selection for all
534 the locales done using the other @code{LC_*} environment variables.  The
535 value of the other @code{LC_*} environment variables is simply ignored
536 in this case.
537
538 @item LC_COLLATE
539 @cindex @code{LC_COLLATE} environment variable
540
541 This specifies what locale to use for string sorting.
542
543 @item LC_CTYPE
544 @cindex @code{LC_CTYPE} environment variable
545
546 This specifies what locale to use for character sets and character
547 classification.
548
549 @item LC_MESSAGES
550 @cindex @code{LC_MESSAGES} environment variable
551
552 This specifies what locale to use for printing messages and to parse
553 responses.
554
555 @item LC_MONETARY
556 @cindex @code{LC_MONETARY} environment variable
557
558 This specifies what locale to use for formatting monetary values.
559
560 @item LC_NUMERIC
561 @cindex @code{LC_NUMERIC} environment variable
562
563 This specifies what locale to use for formatting numbers.
564
565 @item LC_TIME
566 @cindex @code{LC_TIME} environment variable
567
568 This specifies what locale to use for formatting date/time values.
569
570 @item NLSPATH
571 @cindex @code{NLSPATH} environment variable
572
573 This specifies the directories in which the @code{catopen} function
574 looks for message translation catalogs.
575
576 @item _POSIX_OPTION_ORDER
577 @cindex @code{_POSIX_OPTION_ORDER} environment variable.
578
579 If this environment variable is defined, it suppresses the usual
580 reordering of command line arguments by @code{getopt} and
581 @code{argp_parse}.  @xref{Argument Syntax}.
582
583 @c !!! GNU also has COREFILE, CORESERVER, EXECSERVERS
584 @end table
585
586 @node System Calls
587 @section System Calls
588
589 @cindex system call
590 A system call is a request for service that a program makes of the
591 kernel.  The service is generally something that only the kernel has
592 the privilege to do, such as doing I/O.  Programmers don't normally
593 need to be concerned with system calls because there are functions in
594 the GNU C library to do virtually everything that system calls do.
595 These functions work by making system calls themselves.  For example,
596 there is a system call that changes the permissions of a file, but
597 you don't need to know about it because you can just use the GNU C
598 library's @code{chmod} function.
599
600 @cindex kernel call
601 System calls are sometimes called kernel calls.
602
603 However, there are times when you want to make a system call explicitly,
604 and for that, the GNU C library provides the @code{syscall} function.
605 @code{syscall} is harder to use and less portable than functions like
606 @code{chmod}, but easier and more portable than coding the system call
607 in assembler instructions.
608
609 @code{syscall} is most useful when you are working with a system call
610 which is special to your system or is newer than the GNU C library you
611 are using.  @code{syscall} is implemented in an entirely generic way;
612 the function does not know anything about what a particular system
613 call does or even if it is valid.
614
615 The description of @code{syscall} in this section assumes a certain
616 protocol for system calls on the various platforms on which the GNU C
617 library runs.  That protocol is not defined by any strong authority, but
618 we won't describe it here either because anyone who is coding
619 @code{syscall} probably won't accept anything less than kernel and C
620 library source code as a specification of the interface between them
621 anyway.
622
623
624 @code{syscall} is declared in @file{unistd.h}.
625
626 @comment unistd.h
627 @comment ???
628 @deftypefun {long int} syscall (long int @var{sysno}, ...)
629
630 @code{syscall} performs a generic system call.
631
632 @cindex system call number
633 @var{sysno} is the system call number.  Each kind of system call is
634 identified by a number.  Macros for all the possible system call numbers
635 are defined in @file{sys/syscall.h}
636
637 The remaining arguments are the arguments for the system call, in
638 order, and their meanings depend on the kind of system call.  Each kind
639 of system call has a definite number of arguments, from zero to five.
640 If you code more arguments than the system call takes, the extra ones to
641 the right are ignored.
642
643 The return value is the return value from the system call, unless the
644 system call failed.  In that case, @code{syscall} returns @code{-1} and
645 sets @code{errno} to an error code that the system call returned.  Note
646 that system calls do not return @code{-1} when they succeed.
647 @cindex errno
648
649 If you specify an invalid @var{sysno}, @code{syscall} returns @code{-1}
650 with @code{errno} = @code{ENOSYS}.
651
652 Example:
653
654 @smallexample
655
656 #include <unistd.h>
657 #include <sys/syscall.h>
658 #include <errno.h>
659
660 @dots{}
661
662 int rc;
663
664 rc = syscall(SYS_chmod, "/etc/passwd", 0444);
665
666 if (rc == -1)
667    fprintf(stderr, "chmod failed, errno = %d\n", errno);
668
669 @end smallexample
670
671 This, if all the compatibility stars are aligned, is equivalent to the
672 following preferable code:
673
674 @smallexample
675
676 #include <sys/types.h>
677 #include <sys/stat.h>
678 #include <errno.h>
679
680 @dots{}
681
682 int rc;
683
684 rc = chmod("/etc/passwd", 0444);
685 if (rc == -1)
686    fprintf(stderr, "chmod failed, errno = %d\n", errno);
687
688 @end smallexample
689
690 @end deftypefun
691
692
693 @node Program Termination
694 @section Program Termination
695 @cindex program termination
696 @cindex process termination
697
698 @cindex exit status value
699 The usual way for a program to terminate is simply for its @code{main}
700 function to return.  The @dfn{exit status value} returned from the
701 @code{main} function is used to report information back to the process's
702 parent process or shell.
703
704 A program can also terminate normally by calling the @code{exit}
705 function.
706
707 In addition, programs can be terminated by signals; this is discussed in
708 more detail in @ref{Signal Handling}.  The @code{abort} function causes
709 a signal that kills the program.
710
711 @menu
712 * Normal Termination::          If a program calls @code{exit}, a
713                                  process terminates normally.
714 * Exit Status::                 The @code{exit status} provides information
715                                  about why the process terminated.
716 * Cleanups on Exit::            A process can run its own cleanup
717                                  functions upon normal termination.
718 * Aborting a Program::          The @code{abort} function causes
719                                  abnormal program termination.
720 * Termination Internals::       What happens when a process terminates.
721 @end menu
722
723 @node Normal Termination
724 @subsection Normal Termination
725
726 A process terminates normally when its program signals it is done by
727 calling @code{exit}.  Returning from @code{main} is equivalent to
728 calling @code{exit}, and the value that @code{main} returns is used as
729 the argument to @code{exit}.
730
731 @comment stdlib.h
732 @comment ISO
733 @deftypefun void exit (int @var{status})
734 The @code{exit} function tells the system that the program is done, which
735 causes it to terminate the process.
736
737 @var{status} is the program's exit status, which becomes part of the
738 process' termination status.  This function does not return.
739 @end deftypefun
740
741 Normal termination causes the following actions:
742
743 @enumerate
744 @item
745 Functions that were registered with the @code{atexit} or @code{on_exit}
746 functions are called in the reverse order of their registration.  This
747 mechanism allows your application to specify its own ``cleanup'' actions
748 to be performed at program termination.  Typically, this is used to do
749 things like saving program state information in a file, or unlocking
750 locks in shared data bases.
751
752 @item
753 All open streams are closed, writing out any buffered output data.  See
754 @ref{Closing Streams}.  In addition, temporary files opened
755 with the @code{tmpfile} function are removed; see @ref{Temporary Files}.
756
757 @item
758 @code{_exit} is called, terminating the program.  @xref{Termination Internals}.
759 @end enumerate
760
761 @node Exit Status
762 @subsection Exit Status
763 @cindex exit status
764
765 When a program exits, it can return to the parent process a small
766 amount of information about the cause of termination, using the
767 @dfn{exit status}.  This is a value between 0 and 255 that the exiting
768 process passes as an argument to @code{exit}.
769
770 Normally you should use the exit status to report very broad information
771 about success or failure.  You can't provide a lot of detail about the
772 reasons for the failure, and most parent processes would not want much
773 detail anyway.
774
775 There are conventions for what sorts of status values certain programs
776 should return.  The most common convention is simply 0 for success and 1
777 for failure.  Programs that perform comparison use a different
778 convention: they use status 1 to indicate a mismatch, and status 2 to
779 indicate an inability to compare.  Your program should follow an
780 existing convention if an existing convention makes sense for it.
781
782 A general convention reserves status values 128 and up for special
783 purposes.  In particular, the value 128 is used to indicate failure to
784 execute another program in a subprocess.  This convention is not
785 universally obeyed, but it is a good idea to follow it in your programs.
786
787 @strong{Warning:} Don't try to use the number of errors as the exit
788 status.  This is actually not very useful; a parent process would
789 generally not care how many errors occurred.  Worse than that, it does
790 not work, because the status value is truncated to eight bits.
791 Thus, if the program tried to report 256 errors, the parent would
792 receive a report of 0 errors---that is, success.
793
794 For the same reason, it does not work to use the value of @code{errno}
795 as the exit status---these can exceed 255.
796
797 @strong{Portability note:} Some non-POSIX systems use different
798 conventions for exit status values.  For greater portability, you can
799 use the macros @code{EXIT_SUCCESS} and @code{EXIT_FAILURE} for the
800 conventional status value for success and failure, respectively.  They
801 are declared in the file @file{stdlib.h}.
802 @pindex stdlib.h
803
804 @comment stdlib.h
805 @comment ISO
806 @deftypevr Macro int EXIT_SUCCESS
807 This macro can be used with the @code{exit} function to indicate
808 successful program completion.
809
810 On POSIX systems, the value of this macro is @code{0}.  On other
811 systems, the value might be some other (possibly non-constant) integer
812 expression.
813 @end deftypevr
814
815 @comment stdlib.h
816 @comment ISO
817 @deftypevr Macro int EXIT_FAILURE
818 This macro can be used with the @code{exit} function to indicate
819 unsuccessful program completion in a general sense.
820
821 On POSIX systems, the value of this macro is @code{1}.  On other
822 systems, the value might be some other (possibly non-constant) integer
823 expression.  Other nonzero status values also indicate failures.  Certain
824 programs use different nonzero status values to indicate particular
825 kinds of "non-success".  For example, @code{diff} uses status value
826 @code{1} to mean that the files are different, and @code{2} or more to
827 mean that there was difficulty in opening the files.
828 @end deftypevr
829
830 Don't confuse a program's exit status with a process' termination status.
831 There are lots of ways a process can terminate besides having it's program
832 finish.  In the event that the process termination @emph{is} caused by program
833 termination (i.e. @code{exit}), though, the program's exit status becomes
834 part of the process' termination status.
835
836 @node Cleanups on Exit
837 @subsection Cleanups on Exit
838
839 Your program can arrange to run its own cleanup functions if normal
840 termination happens.  If you are writing a library for use in various
841 application programs, then it is unreliable to insist that all
842 applications call the library's cleanup functions explicitly before
843 exiting.  It is much more robust to make the cleanup invisible to the
844 application, by setting up a cleanup function in the library itself
845 using @code{atexit} or @code{on_exit}.
846
847 @comment stdlib.h
848 @comment ISO
849 @deftypefun int atexit (void (*@var{function}) (void))
850 The @code{atexit} function registers the function @var{function} to be
851 called at normal program termination.  The @var{function} is called with
852 no arguments.
853
854 The return value from @code{atexit} is zero on success and nonzero if
855 the function cannot be registered.
856 @end deftypefun
857
858 @comment stdlib.h
859 @comment SunOS
860 @deftypefun int on_exit (void (*@var{function})(int @var{status}, void *@var{arg}), void *@var{arg})
861 This function is a somewhat more powerful variant of @code{atexit}.  It
862 accepts two arguments, a function @var{function} and an arbitrary
863 pointer @var{arg}.  At normal program termination, the @var{function} is
864 called with two arguments:  the @var{status} value passed to @code{exit},
865 and the @var{arg}.
866
867 This function is included in the GNU C library only for compatibility
868 for SunOS, and may not be supported by other implementations.
869 @end deftypefun
870
871 Here's a trivial program that illustrates the use of @code{exit} and
872 @code{atexit}:
873
874 @smallexample
875 @include atexit.c.texi
876 @end smallexample
877
878 @noindent
879 When this program is executed, it just prints the message and exits.
880
881 @node Aborting a Program
882 @subsection Aborting a Program
883 @cindex aborting a program
884
885 You can abort your program using the @code{abort} function.  The prototype
886 for this function is in @file{stdlib.h}.
887 @pindex stdlib.h
888
889 @comment stdlib.h
890 @comment ISO
891 @deftypefun void abort (void)
892 The @code{abort} function causes abnormal program termination.  This
893 does not execute cleanup functions registered with @code{atexit} or
894 @code{on_exit}.
895
896 This function actually terminates the process by raising a
897 @code{SIGABRT} signal, and your program can include a handler to
898 intercept this signal; see @ref{Signal Handling}.
899 @end deftypefun
900
901 @c Put in by rms.  Don't remove.
902 @cartouche
903 @strong{Future Change Warning:} Proposed Federal censorship regulations
904 may prohibit us from giving you information about the possibility of
905 calling this function.  We would be required to say that this is not an
906 acceptable way of terminating a program.
907 @end cartouche
908
909 @node Termination Internals
910 @subsection Termination Internals
911
912 The @code{_exit} function is the primitive used for process termination
913 by @code{exit}.  It is declared in the header file @file{unistd.h}.
914 @pindex unistd.h
915
916 @comment unistd.h
917 @comment POSIX.1
918 @deftypefun void _exit (int @var{status})
919 The @code{_exit} function is the primitive for causing a process to
920 terminate with status @var{status}.  Calling this function does not
921 execute cleanup functions registered with @code{atexit} or
922 @code{on_exit}.
923 @end deftypefun
924
925 @comment stdlib.h
926 @comment ISO
927 @deftypefun void _Exit (int @var{status})
928 The @code{_Exit} function is the @w{ISO C} equivalent to @code{_exit}.
929 The @w{ISO C} committee members were not sure whether the definitions of
930 @code{_exit} and @code{_Exit} were compatible so they have not used the
931 POSIX name.
932
933 This function was introduced in @w{ISO C99} and is declared in
934 @file{stdlib.h}.
935 @end deftypefun
936
937 When a process terminates for any reason---either because the program
938 terminates, or as a result of a signal---the
939 following things happen:
940
941 @itemize @bullet
942 @item
943 All open file descriptors in the process are closed.  @xref{Low-Level I/O}.
944 Note that streams are not flushed automatically when the process
945 terminates; see @ref{I/O on Streams}.
946
947 @item
948 A process exit status is saved to be reported back to the parent process
949 via @code{wait} or @code{waitpid}; see @ref{Process Completion}.  If the
950 program exited, this status includes as its low-order 8 bits the program
951 exit status.
952
953
954 @item
955 Any child processes of the process being terminated are assigned a new
956 parent process.  (On most systems, including GNU, this is the @code{init}
957 process, with process ID 1.)
958
959 @item
960 A @code{SIGCHLD} signal is sent to the parent process.
961
962 @item
963 If the process is a session leader that has a controlling terminal, then
964 a @code{SIGHUP} signal is sent to each process in the foreground job,
965 and the controlling terminal is disassociated from that session.
966 @xref{Job Control}.
967
968 @item
969 If termination of a process causes a process group to become orphaned,
970 and any member of that process group is stopped, then a @code{SIGHUP}
971 signal and a @code{SIGCONT} signal are sent to each process in the
972 group.  @xref{Job Control}.
973 @end itemize