-@node Process Startup
-@chapter Process Startup and Termination
+@node Program Basics, Processes, Signal Handling, Top
+@c %MENU% Writing the beginning and end of your program
+@chapter The Basic Program/System Interface
@cindex process
+@cindex program
+@cindex address space
+@cindex thread of control
@dfn{Processes} are the primitive units for allocation of system
resources. Each process has its own address space and (usually) one
thread of control. A process executes a program; you can have multiple
processes executing the same program, but each process has its own copy
of the program within its own address space and executes it
-independently of the other copies.
-
-This chapter explains what your program should do to handle the startup
-of a process, to terminate its process, and to receive information
-(arguments and the environment) from the parent process.
+independently of the other copies. Though it may have multiple threads
+of control within the same program and a program may be composed of
+multiple logically separate modules, a process always executes exactly
+one program.
+
+Note that we are using a specific definition of ``program'' for the
+purposes of this manual, which corresponds to a common definition in the
+context of Unix systems. In popular usage, ``program'' enjoys a much
+broader definition; it can refer for example to a system's kernel, an
+editor macro, a complex package of software, or a discrete section of
+code executing within a process.
+
+Writing the program is what this manual is all about. This chapter
+explains the most basic interface between your program and the system
+that runs, or calls, it. This includes passing of parameters (arguments
+and environment) from the system, requesting basic services from the
+system, and telling the system the program is done.
+
+A program starts another program with the @code{exec} family of system calls.
+This chapter looks at program startup from the execee's point of view. To
+see the event from the execor's point of view, see @ref{Executing a File}.
@menu
-* Program Arguments:: Parsing your program's command-line arguments.
-* Environment Variables:: How to access parameters inherited from
- a parent process.
-* Program Termination:: How to cause a process to terminate and
- return status information to its parent.
+* Program Arguments:: Parsing your program's command-line arguments
+* Environment Variables:: Less direct parameters affecting your program
+* Auxiliary Vector:: Least direct parameters affecting your program
+* System Calls:: Requesting service from the system
+* Program Termination:: Telling the system you're done; return status
@end menu
-@node Program Arguments
+@node Program Arguments, Environment Variables, , Program Basics
@section Program Arguments
@cindex program arguments
@cindex command line arguments
For the command @samp{cat foo bar}, @var{argc} is 3 and @var{argv} has
three elements, @code{"cat"}, @code{"foo"} and @code{"bar"}.
-If the syntax for the command line arguments to your program is simple
-enough, you can simply pick the arguments off from @var{argv} by hand.
-But unless your program takes a fixed number of arguments, or all of the
-arguments are interpreted in the same way (as file names, for example),
-you are usually better off using @code{getopt} to do the parsing.
-
In Unix systems you can define @code{main} a third way, using three arguments:
@smallexample
-int main (int @var{argc}, char *@var{argv}[], char *@var{envp})
+int main (int @var{argc}, char *@var{argv}[], char *@var{envp}[])
@end smallexample
The first two arguments are just the same. The third argument
-@var{envp} gives the process's environment; it is the same as the value
+@var{envp} gives the program's environment; it is the same as the value
of @code{environ}. @xref{Environment Variables}. POSIX.1 does not
allow this three-argument form, so to be portable it is best to write
@code{main} to take two arguments, and use the value of @code{environ}.
@menu
* Argument Syntax:: By convention, options start with a hyphen.
-* Parsing Options:: The @code{getopt} function.
-* Example of Getopt:: An example of parsing options with @code{getopt}.
-* Long Options:: GNU suggests utilities accept long-named options.
- Here is how to do that.
-* Long Option Example:: An example of using @code{getopt_long}.
-* Suboptions:: Some programs need more detailed options.
-* Suboptions Example:: This shows how it could be done for @code{mount}.
+* Parsing Program Arguments:: Ways to parse program options and arguments.
@end menu
-@node Argument Syntax
+@node Argument Syntax, Parsing Program Arguments, , Program Arguments
@subsection Program Argument Syntax Conventions
@cindex program argument syntax
@cindex syntax, for program arguments
@cindex command argument syntax
POSIX recommends these conventions for command line arguments.
-@code{getopt} (@pxref{Parsing Options}) makes it easy to implement them.
+@code{getopt} (@pxref{Getopt}) and @code{argp_parse} (@pxref{Argp}) make
+it easy to implement them.
@itemize @bullet
@item
@item
Option names are single alphanumeric characters (as for @code{isalnum};
-see @ref{Classification of Characters}).
+@pxref{Classification of Characters}).
@item
Certain options require an argument. For example, the @samp{-o} command
@item
Options typically precede other non-option arguments.
-The implementation of @code{getopt} in the GNU C library normally makes
-it appear as if all the option arguments were specified before all the
-non-option arguments for the purposes of parsing, even if the user of
-your program intermixed option and non-option arguments. It does this
-by reordering the elements of the @var{argv} array. This behavior is
-nonstandard; if you want to suppress it, define the
-@code{_POSIX_OPTION_ORDER} environment variable. @xref{Standard
-Environment}.
+The implementations of @code{getopt} and @code{argp_parse} in @theglibc{}
+normally make it appear as if all the option arguments were
+specified before all the non-option arguments for the purposes of
+parsing, even if the user of your program intermixed option and
+non-option arguments. They do this by reordering the elements of the
+@var{argv} array. This behavior is nonstandard; if you want to suppress
+it, define the @code{_POSIX_OPTION_ORDER} environment variable.
+@xref{Standard Environment}.
@item
The argument @samp{--} terminates all options; any following arguments
@samp{--@var{name}=@var{value}}. This syntax enables a long option to
accept an argument that is itself optional.
-Eventually, the GNU system will provide completion for long option names
+Eventually, @gnusystems{} will provide completion for long option names
in the shell.
-@node Parsing Options
-@subsection Parsing Program Options
+@node Parsing Program Arguments, , Argument Syntax, Program Arguments
+@subsection Parsing Program Arguments
+
@cindex program arguments, parsing
@cindex command arguments, parsing
@cindex parsing program arguments
+If the syntax for the command line arguments to your program is simple
+enough, you can simply pick the arguments off from @var{argv} by hand.
+But unless your program takes a fixed number of arguments, or all of the
+arguments are interpreted in the same way (as file names, for example),
+you are usually better off using @code{getopt} (@pxref{Getopt}) or
+@code{argp_parse} (@pxref{Argp}) to do the parsing.
-Here are the details about how to call the @code{getopt} function. To
-use this facility, your program must include the header file
-@file{unistd.h}.
-@pindex unistd.h
-
-@comment unistd.h
-@comment POSIX.2
-@deftypevar int opterr
-If the value of this variable is nonzero, then @code{getopt} prints an
-error message to the standard error stream if it encounters an unknown
-option character or an option with a missing required argument. This is
-the default behavior. If you set this variable to zero, @code{getopt}
-does not print any messages, but it still returns the character @code{?}
-to indicate an error.
-@end deftypevar
-
-@comment unistd.h
-@comment POSIX.2
-@deftypevar int optopt
-When @code{getopt} encounters an unknown option character or an option
-with a missing required argument, it stores that option character in
-this variable. You can use this for providing your own diagnostic
-messages.
-@end deftypevar
-
-@comment unistd.h
-@comment POSIX.2
-@deftypevar int optind
-This variable is set by @code{getopt} to the index of the next element
-of the @var{argv} array to be processed. Once @code{getopt} has found
-all of the option arguments, you can use this variable to determine
-where the remaining non-option arguments begin. The initial value of
-this variable is @code{1}.
-@end deftypevar
-
-@comment unistd.h
-@comment POSIX.2
-@deftypevar {char *} optarg
-This variable is set by @code{getopt} to point at the value of the
-option argument, for those options that accept arguments.
-@end deftypevar
-
-@comment unistd.h
-@comment POSIX.2
-@deftypefun int getopt (int @var{argc}, char **@var{argv}, const char *@var{options})
-The @code{getopt} function gets the next option argument from the
-argument list specified by the @var{argv} and @var{argc} arguments.
-Normally these values come directly from the arguments received by
-@code{main}.
-
-The @var{options} argument is a string that specifies the option
-characters that are valid for this program. An option character in this
-string can be followed by a colon (@samp{:}) to indicate that it takes a
-required argument.
-
-If the @var{options} argument string begins with a hyphen (@samp{-}), this
-is treated specially. It permits arguments that are not options to be
-returned as if they were associated with option character @samp{\0}.
-
-The @code{getopt} function returns the option character for the next
-command line option. When no more option arguments are available, it
-returns @code{-1}. There may still be more non-option arguments; you
-must compare the external variable @code{optind} against the @var{argc}
-parameter to check this.
-
-If the option has an argument, @code{getopt} returns the argument by
-storing it in the variable @var{optarg}. You don't ordinarily need to
-copy the @code{optarg} string, since it is a pointer into the original
-@var{argv} array, not into a static area that might be overwritten.
-
-If @code{getopt} finds an option character in @var{argv} that was not
-included in @var{options}, or a missing option argument, it returns
-@samp{?} and sets the external variable @code{optopt} to the actual
-option character. If the first character of @var{options} is a colon
-(@samp{:}), then @code{getopt} returns @samp{:} instead of @samp{?} to
-indicate a missing option argument. In addition, if the external
-variable @code{opterr} is nonzero (which is the default), @code{getopt}
-prints an error message.
-@end deftypefun
-
-@node Example of Getopt
-@subsection Example of Parsing Arguments with @code{getopt}
-
-Here is an example showing how @code{getopt} is typically used. The
-key points to notice are:
-
-@itemize @bullet
-@item
-Normally, @code{getopt} is called in a loop. When @code{getopt} returns
-@code{-1}, indicating no more options are present, the loop terminates.
-
-@item
-A @code{switch} statement is used to dispatch on the return value from
-@code{getopt}. In typical use, each case just sets a variable that
-is used later in the program.
-
-@item
-A second loop is used to process the remaining non-option arguments.
-@end itemize
-
-@smallexample
-@include testopt.c.texi
-@end smallexample
-
-Here are some examples showing what this program prints with different
-combinations of arguments:
-
-@smallexample
-% testopt
-aflag = 0, bflag = 0, cvalue = (null)
-
-% testopt -a -b
-aflag = 1, bflag = 1, cvalue = (null)
-
-% testopt -ab
-aflag = 1, bflag = 1, cvalue = (null)
-
-% testopt -c foo
-aflag = 0, bflag = 0, cvalue = foo
-
-% testopt -cfoo
-aflag = 0, bflag = 0, cvalue = foo
-
-% testopt arg1
-aflag = 0, bflag = 0, cvalue = (null)
-Non-option argument arg1
-
-% testopt -a arg1
-aflag = 1, bflag = 0, cvalue = (null)
-Non-option argument arg1
-
-% testopt -c foo arg1
-aflag = 0, bflag = 0, cvalue = foo
-Non-option argument arg1
-
-% testopt -a -- -b
-aflag = 1, bflag = 0, cvalue = (null)
-Non-option argument -b
-
-% testopt -a -
-aflag = 1, bflag = 0, cvalue = (null)
-Non-option argument -
-@end smallexample
-
-@node Long Options
-@subsection Parsing Long Options
-
-To accept GNU-style long options as well as single-character options,
-use @code{getopt_long} instead of @code{getopt}. This function is
-declared in @file{getopt.h}, not @file{unistd.h}. You should make every
-program accept long options if it uses any options, for this takes
-little extra work and helps beginners remember how to use the program.
-
-@comment getopt.h
-@comment GNU
-@deftp {Data Type} {struct option}
-This structure describes a single long option name for the sake of
-@code{getopt_long}. The argument @var{longopts} must be an array of
-these structures, one for each long option. Terminate the array with an
-element containing all zeros.
-
-The @code{struct option} structure has these fields:
+@code{getopt} is more standard (the short-option only version of it is a
+part of the POSIX standard), but using @code{argp_parse} is often
+easier, both for very simple and very complex option structures, because
+it does more of the dirty work for you.
-@table @code
-@item const char *name
-This field is the name of the option. It is a string.
-
-@item int has_arg
-This field says whether the option takes an argument. It is an integer,
-and there are three legitimate values: @w{@code{no_argument}},
-@code{required_argument} and @code{optional_argument}.
-
-@item int *flag
-@itemx int val
-These fields control how to report or act on the option when it occurs.
-
-If @code{flag} is a null pointer, then the @code{val} is a value which
-identifies this option. Often these values are chosen to uniquely
-identify particular long options.
-
-If @code{flag} is not a null pointer, it should be the address of an
-@code{int} variable which is the flag for this option. The value in
-@code{val} is the value to store in the flag to indicate that the option
-was seen.
-@end table
-@end deftp
-
-@comment getopt.h
-@comment GNU
-@deftypefun int getopt_long (int @var{argc}, char **@var{argv}, const char *@var{shortopts}, struct option *@var{longopts}, int *@var{indexptr})
-Decode options from the vector @var{argv} (whose length is @var{argc}).
-The argument @var{shortopts} describes the short options to accept, just as
-it does in @code{getopt}. The argument @var{longopts} describes the long
-options to accept (see above).
-
-When @code{getopt_long} encounters a short option, it does the same
-thing that @code{getopt} would do: it returns the character code for the
-option, and stores the options argument (if it has one) in @code{optarg}.
-
-When @code{getopt_long} encounters a long option, it takes actions based
-on the @code{flag} and @code{val} fields of the definition of that
-option.
-
-If @code{flag} is a null pointer, then @code{getopt_long} returns the
-contents of @code{val} to indicate which option it found. You should
-arrange distinct values in the @code{val} field for options with
-different meanings, so you can decode these values after
-@code{getopt_long} returns. If the long option is equivalent to a short
-option, you can use the short option's character code in @code{val}.
-
-If @code{flag} is not a null pointer, that means this option should just
-set a flag in the program. The flag is a variable of type @code{int}
-that you define. Put the address of the flag in the @code{flag} field.
-Put in the @code{val} field the value you would like this option to
-store in the flag. In this case, @code{getopt_long} returns @code{0}.
-
-For any long option, @code{getopt_long} tells you the index in the array
-@var{longopts} of the options definition, by storing it into
-@code{*@var{indexptr}}. You can get the name of the option with
-@code{@var{longopts}[*@var{indexptr}].name}. So you can distinguish among
-long options either by the values in their @code{val} fields or by their
-indices. You can also distinguish in this way among long options that
-set flags.
-
-When a long option has an argument, @code{getopt_long} puts the argument
-value in the variable @code{optarg} before returning. When the option
-has no argument, the value in @code{optarg} is a null pointer. This is
-how you can tell whether an optional argument was supplied.
-
-When @code{getopt_long} has no more options to handle, it returns
-@code{-1}, and leaves in the variable @code{optind} the index in
-@var{argv} of the next remaining argument.
-@end deftypefun
+@menu
+* Getopt:: Parsing program options using @code{getopt}.
+* Argp:: Parsing program options using @code{argp_parse}.
+* Suboptions:: Some programs need more detailed options.
+* Suboptions Example:: This shows how it could be done for @code{mount}.
+@end menu
-@node Long Option Example
-@subsection Example of Parsing Long Options
+@c Getopt and argp start at the @section level so that there's
+@c enough room for their internal hierarchy (mostly a problem with
+@c argp). -Miles
-@smallexample
-@include longopt.c.texi
-@end smallexample
+@include getopt.texi
+@include argp.texi
-@node Suboptions
-@subsection Parsing of Suboptions
+@node Suboptions, Suboptions Example, Argp, Parsing Program Arguments
+@c This is a @section so that it's at the same level as getopt and argp
+@subsubsection Parsing of Suboptions
Having a single level of options is sometimes not enough. There might
be too many options which have to be available or a set of options is
programming of code like this the function @code{getsubopt} is
available.
-@comment stdlib.h
-@deftypefun int getsubopt (char **@var{optionp}, const char* const *@var{tokens}, char **@var{valuep})
+@deftypefun int getsubopt (char **@var{optionp}, char *const *@var{tokens}, char **@var{valuep})
+@standards{???, stdlib.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c getsubopt ok
+@c strchrnul dup ok
+@c memchr dup ok
+@c strncmp dup ok
The @var{optionp} parameter must be a pointer to a variable containing
-the address of the string to process. When the function returns the
+the address of the string to process. When the function returns, the
reference is updated to point to the next suboption or to the
-terminating @samp{\0} character if there is no more suboption available.
+terminating @samp{\0} character if there are no more suboptions available.
The @var{tokens} parameter references an array of strings containing the
known suboptions. All strings must be @samp{\0} terminated and to mark
function is @samp{-1}.
@end deftypefun
-@node Suboptions Example
+@node Suboptions Example, , Suboptions, Parsing Program Arguments
@subsection Parsing of Suboptions Example
The code which might appear in the @code{mount}(8) program is a perfect
@end smallexample
-@node Environment Variables
+@node Environment Variables, Auxiliary Vector, Program Arguments, Program Basics
@section Environment Variables
@cindex environment variable
@menu
* Environment Access:: How to get and set the values of
- environment variables.
+ environment variables.
* Standard Environment:: These environment variables have
- standard interpretations.
+ standard interpretations.
@end menu
@node Environment Access
@file{stdlib.h}.
@pindex stdlib.h
-@comment stdlib.h
-@comment ISO
+Libraries should use @code{secure_getenv} instead of @code{getenv}, so
+that they do not accidentally use untrusted environment variables.
+Modifications of environment variables are not allowed in
+multi-threaded programs. The @code{getenv} and @code{secure_getenv}
+functions can be safely used in multi-threaded programs.
+
@deftypefun {char *} getenv (const char *@var{name})
+@standards{ISO, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsenv{}}@assafe{}@acsafe{}}
+@c Unguarded access to __environ.
This function returns a string that is the value of the environment
variable @var{name}. You must not modify this string. In some non-Unix
-systems not using the GNU library, it might be overwritten by subsequent
+systems not using @theglibc{}, it might be overwritten by subsequent
calls to @code{getenv} (but not by any other library function). If the
environment variable @var{name} is not defined, the value is a null
pointer.
@end deftypefun
+@deftypefun {char *} secure_getenv (const char *@var{name})
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtsafe{@mtsenv{}}@assafe{}@acsafe{}}
+@c Calls getenv unless secure mode is enabled.
+This function is similar to @code{getenv}, but it returns a null
+pointer if the environment is untrusted. This happens when the
+program file has SUID or SGID bits set. General-purpose libraries
+should always prefer this function over @code{getenv} to avoid
+vulnerabilities if the library is referenced from a SUID/SGID program.
+
+This function is a GNU extension.
+@end deftypefun
+
-@comment stdlib.h
-@comment SVID
-@deftypefun int putenv (const char *@var{string})
+@deftypefun int putenv (char *@var{string})
+@standards{SVID, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c putenv @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c strchr dup ok
+@c strndup dup @ascuheap @acsmem
+@c add_to_environ dup @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c free dup @ascuheap @acsmem
+@c unsetenv dup @mtasuconst:@mtsenv @asulock @aculock
The @code{putenv} function adds or removes definitions from the environment.
If the @var{string} is of the form @samp{@var{name}=@var{value}}, the
definition is added to the environment. Otherwise, the @var{string} is
interpreted as the name of an environment variable, and any definition
for this variable in the environment is removed.
-The GNU library provides this function for compatibility with SVID; it
-may not be available in other systems.
+If the function is successful it returns @code{0}. Otherwise the return
+value is nonzero and @code{errno} is set to indicate the error.
+
+The difference to the @code{setenv} function is that the exact string
+given as the parameter @var{string} is put into the environment. If the
+user should change the string after the @code{putenv} call this will
+reflect automatically in the environment. This also requires that
+@var{string} not be an automatic variable whose scope is left before the
+variable is removed from the environment. The same applies of course to
+dynamically allocated variables which are freed later.
+
+This function is part of the extended Unix interface. You should define
+@var{_XOPEN_SOURCE} before including any header.
+@end deftypefun
+
+
+@deftypefun int setenv (const char *@var{name}, const char *@var{value}, int @var{replace})
+@standards{BSD, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{}}}
+@c setenv @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c add_to_environ @mtasuconst:@mtsenv @ascuheap @asulock @acucorrupt @aculock @acsmem
+@c strlen dup ok
+@c libc_lock_lock @asulock @aculock
+@c strncmp dup ok
+@c realloc dup @ascuheap @acsmem
+@c libc_lock_unlock @aculock
+@c malloc dup @ascuheap @acsmem
+@c free dup @ascuheap @acsmem
+@c mempcpy dup ok
+@c memcpy dup ok
+@c KNOWN_VALUE ok
+@c tfind(strcmp) [no @mtsrace guarded access]
+@c strcmp dup ok
+@c STORE_VALUE @ascuheap @acucorrupt @acsmem
+@c tsearch(strcmp) @ascuheap @acucorrupt @acsmem [no @mtsrace or @asucorrupt guarded access makes for mtsafe and @asulock]
+@c strcmp dup ok
+The @code{setenv} function can be used to add a new definition to the
+environment. The entry with the name @var{name} is replaced by the
+value @samp{@var{name}=@var{value}}. Please note that this is also true
+if @var{value} is the empty string. To do this a new string is created
+and the strings @var{name} and @var{value} are copied. A null pointer
+for the @var{value} parameter is illegal. If the environment already
+contains an entry with key @var{name} the @var{replace} parameter
+controls the action. If replace is zero, nothing happens. Otherwise
+the old entry is replaced by the new one.
+
+Please note that you cannot remove an entry completely using this function.
+
+If the function is successful it returns @code{0}. Otherwise the
+environment is unchanged and the return value is @code{-1} and
+@code{errno} is set.
+
+This function was originally part of the BSD library but is now part of
+the Unix standard.
+@end deftypefun
+
+@deftypefun int unsetenv (const char *@var{name})
+@standards{BSD, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@c unsetenv @mtasuconst:@mtsenv @asulock @aculock
+@c strchr dup ok
+@c strlen dup ok
+@c libc_lock_lock @asulock @aculock
+@c strncmp dup ok
+@c libc_lock_unlock @aculock
+Using this function one can remove an entry completely from the
+environment. If the environment contains an entry with the key
+@var{name} this whole entry is removed. A call to this function is
+equivalent to a call to @code{putenv} when the @var{value} part of the
+string is empty.
+
+The function returns @code{-1} if @var{name} is a null pointer, points to
+an empty string, or points to a string containing a @code{=} character.
+It returns @code{0} if the call succeeded.
+
+This function was originally part of the BSD library but is now part of
+the Unix standard. The BSD version had no return value, though.
+@end deftypefun
+
+There is one more function to modify the whole environment. This
+function is said to be used in the POSIX.9 (POSIX bindings for Fortran
+77) and so one should expect it did made it into POSIX.1. But this
+never happened. But we still provide this function as a GNU extension
+to enable writing standard compliant Fortran environments.
+
+@deftypefun int clearenv (void)
+@standards{GNU, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasuconst{:@mtsenv{}}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
+@c clearenv @mtasuconst:@mtsenv @ascuheap @asulock @aculock @acsmem
+@c libc_lock_lock @asulock @aculock
+@c free dup @ascuheap @acsmem
+@c libc_lock_unlock @aculock
+The @code{clearenv} function removes all entries from the environment.
+Using @code{putenv} and @code{setenv} new entries can be added again
+later.
+
+If the function is successful it returns @code{0}. Otherwise the return
+value is nonzero.
@end deftypefun
-@c !!! BSD function setenv
You can deal directly with the underlying representation of environment
objects to add more variables to the environment (for example, to
-communicate with another program you are about to execute; see
-@ref{Executing a File}).
+communicate with another program you are about to execute;
+@pxref{Executing a File}).
-@comment unistd.h
-@comment POSIX.1
@deftypevar {char **} environ
+@standards{POSIX.1, unistd.h}
The environment is represented as an array of strings. Each string is
of the format @samp{@var{name}=@var{value}}. The order in which
strings appear in the environment is not significant, but the same
@code{getenv}.
@end deftypevar
-Unix systems, and the GNU system, pass the initial value of
+Unix systems, and @gnusystems{}, pass the initial value of
@code{environ} as the third argument to @code{main}.
@xref{Program Arguments}.
@comment Extra blank lines make it look better.
@table @code
@item HOME
-@cindex HOME environment variable
+@cindex @code{HOME} environment variable
@cindex home directory
This is a string representing the user's @dfn{home directory}, or
@c !!! also USER
@item LOGNAME
-@cindex LOGNAME environment variable
+@cindex @code{LOGNAME} environment variable
This is the name that the user used to log in. Since the value in the
environment can be tweaked arbitrarily, this is not a reliable way to
-identify the user who is running a process; a function like
+identify the user who is running a program; a function like
@code{getlogin} (@pxref{Who Logged In}) is better for that purpose.
For most purposes, it is better to use @code{LOGNAME}, precisely because
this lets the user specify the value.
@item PATH
-@cindex PATH environment variable
+@cindex @code{PATH} environment variable
A @dfn{path} is a sequence of directory names which is used for
searching for a file. The variable @code{PATH} holds a path used
@c !!! also TERMCAP
@item TERM
-@cindex TERM environment variable
+@cindex @code{TERM} environment variable
This specifies the kind of terminal that is receiving program output.
Some programs can make use of this information to take advantage of
Manual}) use the @code{TERM} environment variable, for example.
@item TZ
-@cindex TZ environment variable
+@cindex @code{TZ} environment variable
This specifies the time zone. @xref{TZ Variable}, for information about
the format of this string and how it is used.
@item LANG
-@cindex LANG environment variable
+@cindex @code{LANG} environment variable
This specifies the default locale to use for attribute categories where
neither @code{LC_ALL} nor the specific environment variable for that
@ignore
@c I doubt this really exists
@item LC_ALL
-@cindex LC_ALL environment variable
+@cindex @code{LC_ALL} environment variable
This is similar to the @code{LANG} environment variable. However, its
value takes precedence over any values provided for the individual
environment variable.
@end ignore
+@item LC_ALL
+@cindex @code{LC_ALL} environment variable
+
+If this environment variable is set it overrides the selection for all
+the locales done using the other @code{LC_*} environment variables. The
+value of the other @code{LC_*} environment variables is simply ignored
+in this case.
+
@item LC_COLLATE
-@cindex LC_COLLATE environment variable
+@cindex @code{LC_COLLATE} environment variable
This specifies what locale to use for string sorting.
@item LC_CTYPE
-@cindex LC_CTYPE environment variable
+@cindex @code{LC_CTYPE} environment variable
This specifies what locale to use for character sets and character
classification.
+@item LC_MESSAGES
+@cindex @code{LC_MESSAGES} environment variable
+
+This specifies what locale to use for printing messages and to parse
+responses.
+
@item LC_MONETARY
-@cindex LC_MONETARY environment variable
+@cindex @code{LC_MONETARY} environment variable
This specifies what locale to use for formatting monetary values.
@item LC_NUMERIC
-@cindex LC_NUMERIC environment variable
+@cindex @code{LC_NUMERIC} environment variable
This specifies what locale to use for formatting numbers.
@item LC_TIME
-@cindex LC_TIME environment variable
+@cindex @code{LC_TIME} environment variable
This specifies what locale to use for formatting date/time values.
+@item NLSPATH
+@cindex @code{NLSPATH} environment variable
+
+This specifies the directories in which the @code{catopen} function
+looks for message translation catalogs.
+
@item _POSIX_OPTION_ORDER
-@cindex _POSIX_OPTION_ORDER environment variable.
+@cindex @code{_POSIX_OPTION_ORDER} environment variable.
If this environment variable is defined, it suppresses the usual
-reordering of command line arguments by @code{getopt}. @xref{Argument Syntax}.
+reordering of command line arguments by @code{getopt} and
+@code{argp_parse}. @xref{Argument Syntax}.
@c !!! GNU also has COREFILE, CORESERVER, EXECSERVERS
@end table
+@node Auxiliary Vector
+@section Auxiliary Vector
+@cindex auxiliary vector
+
+When a program is executed, it receives information from the operating
+system about the environment in which it is operating. The form of this
+information is a table of key-value pairs, where the keys are from the
+set of @samp{AT_} values in @file{elf.h}. Some of the data is provided
+by the kernel for libc consumption, and may be obtained by ordinary
+interfaces, such as @code{sysconf}. However, on a platform-by-platform
+basis there may be information that is not available any other way.
+
+@subsection Definition of @code{getauxval}
+@deftypefun {unsigned long int} getauxval (unsigned long int @var{type})
+@standards{???, sys/auxv.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Reads from hwcap or iterates over constant auxv.
+This function is used to inquire about the entries in the auxiliary
+vector. The @var{type} argument should be one of the @samp{AT_} symbols
+defined in @file{elf.h}. If a matching entry is found, the value is
+returned; if the entry is not found, zero is returned and @code{errno} is
+set to @code{ENOENT}.
+@end deftypefun
+
+For some platforms, the key @code{AT_HWCAP} is the easiest way to inquire
+about any instruction set extensions available at runtime. In this case,
+there will (of necessity) be a platform-specific set of @samp{HWCAP_}
+values masked together that describe the capabilities of the cpu on which
+the program is being executed.
+
+@node System Calls
+@section System Calls
+
+@cindex system call
+A system call is a request for service that a program makes of the
+kernel. The service is generally something that only the kernel has
+the privilege to do, such as doing I/O. Programmers don't normally
+need to be concerned with system calls because there are functions in
+@theglibc{} to do virtually everything that system calls do.
+These functions work by making system calls themselves. For example,
+there is a system call that changes the permissions of a file, but
+you don't need to know about it because you can just use @theglibc{}'s
+@code{chmod} function.
+
+@cindex kernel call
+System calls are sometimes called kernel calls.
+
+However, there are times when you want to make a system call explicitly,
+and for that, @theglibc{} provides the @code{syscall} function.
+@code{syscall} is harder to use and less portable than functions like
+@code{chmod}, but easier and more portable than coding the system call
+in assembler instructions.
+
+@code{syscall} is most useful when you are working with a system call
+which is special to your system or is newer than @theglibc{} you
+are using. @code{syscall} is implemented in an entirely generic way;
+the function does not know anything about what a particular system
+call does or even if it is valid.
+
+The description of @code{syscall} in this section assumes a certain
+protocol for system calls on the various platforms on which @theglibc{}
+runs. That protocol is not defined by any strong authority, but
+we won't describe it here either because anyone who is coding
+@code{syscall} probably won't accept anything less than kernel and C
+library source code as a specification of the interface between them
+anyway.
+
+
+@code{syscall} is declared in @file{unistd.h}.
+
+@deftypefun {long int} syscall (long int @var{sysno}, @dots{})
+@standards{???, unistd.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+@code{syscall} performs a generic system call.
+
+@cindex system call number
+@var{sysno} is the system call number. Each kind of system call is
+identified by a number. Macros for all the possible system call numbers
+are defined in @file{sys/syscall.h}
+
+The remaining arguments are the arguments for the system call, in
+order, and their meanings depend on the kind of system call. Each kind
+of system call has a definite number of arguments, from zero to five.
+If you code more arguments than the system call takes, the extra ones to
+the right are ignored.
+
+The return value is the return value from the system call, unless the
+system call failed. In that case, @code{syscall} returns @code{-1} and
+sets @code{errno} to an error code that the system call returned. Note
+that system calls do not return @code{-1} when they succeed.
+@cindex errno
+
+If you specify an invalid @var{sysno}, @code{syscall} returns @code{-1}
+with @code{errno} = @code{ENOSYS}.
+
+Example:
+
+@smallexample
+
+#include <unistd.h>
+#include <sys/syscall.h>
+#include <errno.h>
+
+@dots{}
+
+int rc;
+
+rc = syscall(SYS_chmod, "/etc/passwd", 0444);
+
+if (rc == -1)
+ fprintf(stderr, "chmod failed, errno = %d\n", errno);
+
+@end smallexample
+
+This, if all the compatibility stars are aligned, is equivalent to the
+following preferable code:
+
+@smallexample
+
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <errno.h>
+
+@dots{}
+
+int rc;
+
+rc = chmod("/etc/passwd", 0444);
+if (rc == -1)
+ fprintf(stderr, "chmod failed, errno = %d\n", errno);
+
+@end smallexample
+
+@end deftypefun
+
+
@node Program Termination
@section Program Termination
@cindex program termination
@node Normal Termination
@subsection Normal Termination
-A process terminates normally when the program calls @code{exit}.
-Returning from @code{main} is equivalent to calling @code{exit}, and
-the value that @code{main} returns is used as the argument to @code{exit}.
+A process terminates normally when its program signals it is done by
+calling @code{exit}. Returning from @code{main} is equivalent to
+calling @code{exit}, and the value that @code{main} returns is used as
+the argument to @code{exit}.
-@comment stdlib.h
-@comment ISO
@deftypefun void exit (int @var{status})
-The @code{exit} function terminates the process with status
-@var{status}. This function does not return.
+@standards{ISO, stdlib.h}
+@safety{@prelim{}@mtunsafe{@mtasurace{:exit}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
+@c Access to the atexit/on_exit list, the libc_atexit hook and tls dtors
+@c is not guarded. Streams must be flushed, and that triggers the usual
+@c AS and AC issues with streams.
+The @code{exit} function tells the system that the program is done, which
+causes it to terminate the process.
+
+@var{status} is the program's exit status, which becomes part of the
+process' termination status. This function does not return.
@end deftypefun
Normal termination causes the following actions:
are declared in the file @file{stdlib.h}.
@pindex stdlib.h
-@comment stdlib.h
-@comment ISO
@deftypevr Macro int EXIT_SUCCESS
+@standards{ISO, stdlib.h}
This macro can be used with the @code{exit} function to indicate
successful program completion.
expression.
@end deftypevr
-@comment stdlib.h
-@comment ISO
@deftypevr Macro int EXIT_FAILURE
+@standards{ISO, stdlib.h}
This macro can be used with the @code{exit} function to indicate
unsuccessful program completion in a general sense.
mean that there was difficulty in opening the files.
@end deftypevr
+Don't confuse a program's exit status with a process' termination status.
+There are lots of ways a process can terminate besides having its program
+finish. In the event that the process termination @emph{is} caused by program
+termination (i.e., @code{exit}), though, the program's exit status becomes
+part of the process' termination status.
+
@node Cleanups on Exit
@subsection Cleanups on Exit
application, by setting up a cleanup function in the library itself
using @code{atexit} or @code{on_exit}.
-@comment stdlib.h
-@comment ISO
@deftypefun int atexit (void (*@var{function}) (void))
+@standards{ISO, stdlib.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
+@c atexit @ascuheap @asulock @aculock @acsmem
+@c cxa_atexit @ascuheap @asulock @aculock @acsmem
+@c __internal_atexit @ascuheap @asulock @aculock @acsmem
+@c __new_exitfn @ascuheap @asulock @aculock @acsmem
+@c __libc_lock_lock @asulock @aculock
+@c calloc dup @ascuheap @acsmem
+@c __libc_lock_unlock @aculock
+@c atomic_write_barrier dup ok
The @code{atexit} function registers the function @var{function} to be
called at normal program termination. The @var{function} is called with
no arguments.
the function cannot be registered.
@end deftypefun
-@comment stdlib.h
-@comment SunOS
@deftypefun int on_exit (void (*@var{function})(int @var{status}, void *@var{arg}), void *@var{arg})
+@standards{SunOS, stdlib.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
+@c on_exit @ascuheap @asulock @aculock @acsmem
+@c new_exitfn dup @ascuheap @asulock @aculock @acsmem
+@c atomic_write_barrier dup ok
This function is a somewhat more powerful variant of @code{atexit}. It
accepts two arguments, a function @var{function} and an arbitrary
pointer @var{arg}. At normal program termination, the @var{function} is
called with two arguments: the @var{status} value passed to @code{exit},
and the @var{arg}.
-This function is included in the GNU C library only for compatibility
+This function is included in @theglibc{} only for compatibility
for SunOS, and may not be supported by other implementations.
@end deftypefun
for this function is in @file{stdlib.h}.
@pindex stdlib.h
-@comment stdlib.h
-@comment ISO
@deftypefun void abort (void)
+@standards{ISO, stdlib.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
+@c The implementation takes a recursive lock and attempts to support
+@c calls from signal handlers, but if we're in the middle of flushing or
+@c using streams, we may encounter them in inconsistent states.
The @code{abort} function causes abnormal program termination. This
does not execute cleanup functions registered with @code{atexit} or
@code{on_exit}.
by @code{exit}. It is declared in the header file @file{unistd.h}.
@pindex unistd.h
-@comment unistd.h
-@comment POSIX.1
@deftypefun void _exit (int @var{status})
+@standards{POSIX.1, unistd.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Direct syscall (exit_group or exit); calls __task_terminate on hurd,
+@c and abort in the generic posix implementation.
The @code{_exit} function is the primitive for causing a process to
terminate with status @var{status}. Calling this function does not
execute cleanup functions registered with @code{atexit} or
@code{on_exit}.
@end deftypefun
-When a process terminates for any reason---either by an explicit
-termination call, or termination as a result of a signal---the
+@deftypefun void _Exit (int @var{status})
+@standards{ISO, stdlib.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Alias for _exit.
+The @code{_Exit} function is the @w{ISO C} equivalent to @code{_exit}.
+The @w{ISO C} committee members were not sure whether the definitions of
+@code{_exit} and @code{_Exit} were compatible so they have not used the
+POSIX name.
+
+This function was introduced in @w{ISO C99} and is declared in
+@file{stdlib.h}.
+@end deftypefun
+
+When a process terminates for any reason---either because the program
+terminates, or as a result of a signal---the
following things happen:
@itemize @bullet
@item
All open file descriptors in the process are closed. @xref{Low-Level I/O}.
Note that streams are not flushed automatically when the process
-terminates; @xref{I/O on Streams}.
+terminates; see @ref{I/O on Streams}.
@item
-The low-order 8 bits of the return status code are saved to be reported
-back to the parent process via @code{wait} or @code{waitpid}; see
-@ref{Process Completion}.
+A process exit status is saved to be reported back to the parent process
+via @code{wait} or @code{waitpid}; see @ref{Process Completion}. If the
+program exited, this status includes as its low-order 8 bits the program
+exit status.
+
@item
Any child processes of the process being terminated are assigned a new
projects / thirdparty / glibc.git / blobdiff