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