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