(grow_heap): When growing bail even if new_size is negative.
[kopensolaris-gnu/glibc.git] / manual / startup.texi
index a816093..5ccb78b 100644 (file)
@@ -1,44 +1,67 @@
-@node Process Startup, Child Processes, Signal Handling, Top
-@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 system.  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, @xref{Executing a File}.
 
 @menu
-* Program Arguments::           Parsing the command-line arguments to
-                                a program.
-* 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
+* System Calls::                Requesting service from the system
+* Program Termination::         Telling the system you're done; return status
 @end menu
 
-@node Program Arguments, Environment Variables,  , Processes
+@node Program Arguments
 @section Program Arguments
 @cindex program arguments
 @cindex command line arguments
+@cindex arguments, to program
 
+@cindex program startup
+@cindex startup of program
+@cindex invocation of program
 @cindex @code{main} function
+@findex main
 The system starts a C program by calling the function @code{main}.  It
 is up to you to write a function named @code{main}---otherwise, you
 won't even be able to link your program without errors.
 
-You can define @code{main} either to take no arguments, or to take two
-arguments that represent the command line arguments to the program, like
-this:
+In @w{ISO C} you can define @code{main} either to take no arguments, or to
+take two arguments that represent the command line arguments to the
+program, like this:
 
-@example
+@smallexample
 int main (int @var{argc}, char *@var{argv}[])
-@end example
+@end smallexample
 
 @cindex argc (program argument count)
 @cindex argv (program argument vector)
@@ -60,29 +83,32 @@ is this null pointer.
 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}[])
+@end smallexample
+
+The first two arguments are just the same.  The third argument
+@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}.
+* Argument Syntax::             By convention, options start with a hyphen.
+* 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
@@ -95,28 +121,28 @@ the options do not take arguments.  Thus, @samp{-abc} is equivalent to
 
 @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
 of the @code{ld} command requires an argument---an output file name.
 
 @item
-An option and its argument may or may appear as separate tokens.  (In
+An option and its argument may or may not appear as separate tokens.  (In
 other words, the whitespace separating them is optional.)  Thus,
-@samp{-o foo} and @samp{-ofoo} are equivalent.
+@w{@samp{-o foo}} and @samp{-ofoo} are equivalent.
 
 @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 the GNU C
+library 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
@@ -134,10 +160,10 @@ interpretation is left up to the particular application program.
 
 @cindex long-named options
 GNU adds @dfn{long options} to these conventions.  Long options consist
-of @samp{--} followed by a name made of alphanumeric characters.  Option
-names are typically one to three words long, with hyphens to separate
-words.  Users can abbreviate the option names as long as the
-abbreviations are unique.
+of @samp{--} followed by a name made of alphanumeric characters and
+dashes.  Option names are typically one to three words long, with
+hyphens to separate words.  Users can abbreviate the option names as
+long as the abbreviations are unique.
 
 To specify an argument for a long option, write
 @samp{--@var{name}=@var{value}}.  This syntax enables a long option to
@@ -146,247 +172,90 @@ accept an argument that is itself optional.
 Eventually, the GNU system 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 @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 without an option 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{argv}
-parameter to check this.
-
-If the options has an argument, @code{getopt} returns the argument by
-storing it in the varables @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.  In addition, if the external variable @code{opterr}
-is nonzero, @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
-
-@example
-@include testopt.c.texi
-@end example
-
-Here are some examples showing what this program prints with different
-combinations of arguments:
-
-@example
-% 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 example
-
-@node Long Options
-@subsection Parsing Long Options
+@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.
 
-To accept GNU-style long options as well as single-character options,
-use the function @code{getopt_long} instead of @code{getopt}.  You
-should do this in every program that uses options, for it takes little
-extra work and helps beginners remember how to use the program.
+@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
 
-@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.
+@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
 
-The @code{struct option} structure has these fields:
+@include getopt.texi
+@include argp.texi
 
-@table @code
-@item name
-This field is the name of the option.  It is a string.
+@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
 
-@item has_arg
-This field says whether the option takes an argument.  It is an integer,
-and there are three legitimate values: @code{no_argument},
-@code{required_argument} and @code{optional_argument}.
+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
+closely related.
 
-@item flag
-@itemx val
-These fields control how to report or act on the option when it occurs.
+For this case some programs use suboptions.  One of the most prominent
+programs is certainly @code{mount}(8).  The @code{-o} option take one
+argument which itself is a comma separated list of options.  To ease the
+programming of code like this the function @code{getsubopt} is
+available.
 
-If @code{flag} is zero, then the @code{val} is a value which identifies
-this option.  Often these values are chosen to uniquely identify
-particular long options.
+@comment stdlib.h
+@deftypefun int getsubopt (char **@var{optionp}, const char* const *@var{tokens}, char **@var{valuep})
+
+The @var{optionp} parameter must be a pointer to a variable containing
+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.
+
+The @var{tokens} parameter references an array of strings containing the
+known suboptions.  All strings must be @samp{\0} terminated and to mark
+the end a null pointer must be stored.  When @code{getsubopt} finds a
+possible legal suboption it compares it with all strings available in
+the @var{tokens} array and returns the index in the string as the
+indicator.
+
+In case the suboption has an associated value introduced by a @samp{=}
+character, a pointer to the value is returned in @var{valuep}.  The
+string is @samp{\0} terminated.  If no argument is available
+@var{valuep} is set to the null pointer.  By doing this the caller can
+check whether a necessary value is given or whether no unexpected value
+is present.
+
+In case the next suboption in the string is not mentioned in the
+@var{tokens} array the starting address of the suboption including a
+possible value is returned in @var{valuep} and the return value of the
+function is @samp{-1}.
+@end deftypefun
 
-If @code{flag} is nonzero, 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
+@node Suboptions Example, , Suboptions, Parsing Program Arguments
+@subsection Parsing of Suboptions Example
 
-@comment getopt.h
-@comment GNU
-@deftypefun getopt_long (int @var{argc}, char **@var{argv}, const char *@var{short}, struct option *@var{long}, int *@var{indexptr})
-Decode options from the vector @var{argv} (whose length is @var{argc}).
-The argument @var{short} describes the short options to accept, just as
-it does in @code{getopt}.  The argument @var{long} 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 zero, 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 nonzero, 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{long} of the options definition, by storing it into
-@code{*@var{indexptr}}.  You can get the name of the option with
-@code{@var{long}[*@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 @code{0}.  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
+The code which might appear in the @code{mount}(8) program is a perfect
+example of the use of @code{getsubopt}:
 
-@node Long Option Example
-@subsection Example of Parsing Long Options
+@smallexample
+@include subopt.c.texi
+@end smallexample
 
-@example
-@include longopts.c.texi
-@end example
 
 @node Environment Variables
 @section Environment Variables
@@ -395,19 +264,20 @@ When @code{getopt_long} has no more options to handle, it returns
 When a program is executed, it receives information about the context in
 which it was invoked in two ways.  The first mechanism uses the
 @var{argv} and @var{argc} arguments to its @code{main} function, and is
-discussed in @ref{Program Arguments}.  The second mechanism is
-uses @dfn{environment variables} and is discussed in this section.
+discussed in @ref{Program Arguments}.  The second mechanism uses
+@dfn{environment variables} and is discussed in this section.
 
 The @var{argv} mechanism is typically used to pass command-line
 arguments specific to the particular program being invoked.  The
 environment, on the other hand, keeps track of information that is
 shared by many programs, changes infrequently, and that is less
-frequently accessed.
+frequently used.
 
 The environment variables discussed in this section are the same
 environment variables that you set using assignments and the
 @code{export} command in the shell.  Programs executed from the shell
 inherit all of the environment variables from the shell.
+@c !!! xref to right part of bash manual when it exists
 
 @cindex environment
 Standard environment variables are used for information about the user's
@@ -426,10 +296,10 @@ character, since this is assumed to terminate the string.
 
 
 @menu
-* Environment Access::    How to get and set the values of
-                          environment variables.
-* Standard Environment::  These environment variables have
-                          standard interpretations.
+* Environment Access::          How to get and set the values of
+                                environment variables.
+* Standard Environment::        These environment variables have
+                                standard interpretations.
 @end menu
 
 @node Environment Access
@@ -439,16 +309,18 @@ character, since this is assumed to terminate the string.
 
 The value of an environment variable can be accessed with the
 @code{getenv} function.  This is declared in the header file
-@file{stdlib.h}.
+@file{stdlib.h}.  All of the following functions can be safely used in
+multi-threaded programs.  It is made sure that concurrent modifications
+to the environment do not lead to errors.
 @pindex stdlib.h
 
 @comment stdlib.h
-@comment ANSI
+@comment ISO
 @deftypefun {char *} getenv (const char *@var{name})
 This function returns a string that is the value of the environment
-variable @var{name}.  You must not modify this string.  In some systems
-not using the GNU library, it might be overwritten by subsequent calls
-to @code{getenv} (but not by any other library function).  If the
+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
+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
@@ -456,21 +328,85 @@ pointer.
 
 @comment stdlib.h
 @comment SVID
-@deftypefun int putenv (const char *@var{string})
+@deftypefun int putenv (char *@var{string})
 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.
+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 in automatically in the environment.  This also requires that
+@var{string} is no automatic variable which 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.  Since it was also
+available in old SVID libraries you should define either
+@var{_XOPEN_SOURCE} or @var{_SVID_SOURCE} before including any header.
+@end deftypefun
+
+
+@comment stdlib.h
+@comment BSD
+@deftypefun int setenv (const char *@var{name}, const char *@var{value}, int @var{replace})
+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.
+
+This function was originally part of the BSD library but is now part of
+the Unix standard.
+@end deftypefun
+
+@comment stdlib.h
+@comment BSD
+@deftypefun int unsetenv (const char *@var{name})
+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 return @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.
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int clearenv (void)
+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
 
+
 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
@@ -481,26 +417,31 @@ strings appear in the environment is not significant, but the same
 @var{name} must not appear more than once.  The last element of the
 array is a null pointer.
 
-This variable is not declared in any header file, but if you declare it
-in your own program as @code{extern}, the right thing will happen.
+This variable is declared in the header file @file{unistd.h}.
 
 If you just want to get the value of an environment variable, use
 @code{getenv}.
 @end deftypevar
 
+Unix systems, and the GNU system, pass the initial value of
+@code{environ} as the third argument to @code{main}.
+@xref{Program Arguments}.
+
 @node Standard Environment
 @subsection Standard Environment Variables
 @cindex standard environment variables
 
 These environment variables have standard meanings.  This doesn't mean
 that they are always present in the environment; but if these variables
-@emph{are} present, they have these meanings, and that you shouldn't try
-to use these environment variable names for some other purpose.
+@emph{are} present, they have these meanings.  You shouldn't try to use
+these environment variable names for some other purpose.
 
+@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
 initial default working directory.
 
@@ -512,21 +453,23 @@ look up the user's name in the user database (@pxref{User Database}).
 For most purposes, it is better to use @code{HOME}, precisely because
 this lets the user specify the value.
 
+@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
-@code{getlogin} (@pxref{User Identification Functions}) is better for
-that purpose.
+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 @var{PATH} holds a path used
+searching for a file.  The variable @code{PATH} holds a path used
 for searching for programs to be run.
 
 The @code{execlp} and @code{execvp} functions (@pxref{Executing a File})
@@ -534,22 +477,24 @@ use this environment variable, as do many shells and other utilities
 which are implemented in terms of those functions.
 
 The syntax of a path is a sequence of directory names separated by
-colons.  An empty string instead of a directory name stands for the 
+colons.  An empty string instead of a directory name stands for the
 current directory (@pxref{Working Directory}).
 
 A typical value for this environment variable might be a string like:
 
-@example
-.:/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local:/usr/local/bin
-@end example
+@smallexample
+:/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local/bin
+@end smallexample
 
 This means that if the user tries to execute a program named @code{foo},
-the system will look for files named @file{./foo}, @file{/bin/foo},
+the system will look for files named @file{foo}, @file{/bin/foo},
 @file{/etc/foo}, and so on.  The first of these files that exists is
 the one that is executed.
 
+@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
 special escape sequences or terminal modes supported by particular kinds
@@ -558,12 +503,14 @@ of terminals.  Many programs which use the termcap library
 Manual}) use the @code{TERM} environment variable, for example.
 
 @item TZ
-@cindex TZ environment variable
-This specifies the time zone.  @xref{Time Zone}, for information about
+@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
 category is set.  @xref{Locales}, for more information about
@@ -572,40 +519,177 @@ locales.
 @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
 attribute category environment variables, or for the @code{LANG}
 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 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
+the GNU C library 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 the GNU C
+library'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, the GNU C library 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 the GNU C library 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 the GNU C
+library 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}.
+
+@comment unistd.h
+@comment ???
+@deftypefun {long int} syscall (long int @var{sysno}, ...)
+
+@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
@@ -625,31 +709,39 @@ more detail in @ref{Signal Handling}.  The @code{abort} function causes
 a signal that kills the program.
 
 @menu
-* Normal Termination::  
-* Exit Status::                 Exit Status
-* Cleanups on Exit::            Cleanups on Exit
-* Aborting a Program::          
-* Termination Internals::       Termination Internals
+* Normal Termination::          If a program calls @code{exit}, a
+                                 process terminates normally.
+* Exit Status::                 The @code{exit status} provides information
+                                 about why the process terminated.
+* Cleanups on Exit::            A process can run its own cleanup
+                                 functions upon normal termination.
+* Aborting a Program::          The @code{abort} function causes
+                                 abnormal program termination.
+* Termination Internals::       What happens when a process terminates.
 @end menu
 
 @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 ANSI
+@comment ISO
 @deftypefun void exit (int @var{status})
-The @code{exit} function terminates the process with status
-@var{status}.  This function does not return.
+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:
 
 @enumerate
-@item 
+@item
 Functions that were registered with the @code{atexit} or @code{on_exit}
 functions are called in the reverse order of their registration.  This
 mechanism allows your application to specify its own ``cleanup'' actions
@@ -657,13 +749,13 @@ to be performed at program termination.  Typically, this is used to do
 things like saving program state information in a file, or unlocking
 locks in shared data bases.
 
-@item 
+@item
 All open streams are closed, writing out any buffered output data.  See
-@ref{Opening and Closing Streams}.  In addition, temporary files opened
+@ref{Closing Streams}.  In addition, temporary files opened
 with the @code{tmpfile} function are removed; see @ref{Temporary Files}.
 
-@item 
-@code{_exit} is called.  @xref{Termination Internals}.
+@item
+@code{_exit} is called, terminating the program.  @xref{Termination Internals}.
 @end enumerate
 
 @node Exit Status
@@ -710,7 +802,7 @@ are declared in the file @file{stdlib.h}.
 @pindex stdlib.h
 
 @comment stdlib.h
-@comment ANSI
+@comment ISO
 @deftypevr Macro int EXIT_SUCCESS
 This macro can be used with the @code{exit} function to indicate
 successful program completion.
@@ -721,20 +813,26 @@ expression.
 @end deftypevr
 
 @comment stdlib.h
-@comment ANSI
+@comment ISO
 @deftypevr Macro int EXIT_FAILURE
 This macro can be used with the @code{exit} function to indicate
 unsuccessful program completion in a general sense.
 
 On POSIX systems, the value of this macro is @code{1}.  On other
 systems, the value might be some other (possibly non-constant) integer
-expression.  Other nonzero status values also indicate future.  Certain
+expression.  Other nonzero status values also indicate failures.  Certain
 programs use different nonzero status values to indicate particular
 kinds of "non-success".  For example, @code{diff} uses status value
 @code{1} to mean that the files are different, and @code{2} or more to
 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 it's 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
 
@@ -747,14 +845,14 @@ application, by setting up a cleanup function in the library itself
 using @code{atexit} or @code{on_exit}.
 
 @comment stdlib.h
-@comment ANSI
-@deftypefun int atexit (void (*@var{function}) ())
+@comment ISO
+@deftypefun int atexit (void (*@var{function}) (void))
 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 return value from @code{atexit} is zero on success and nonzero if
-the function cannot be registered. 
+the function cannot be registered.
 @end deftypefun
 
 @comment stdlib.h
@@ -773,23 +871,9 @@ for SunOS, and may not be supported by other implementations.
 Here's a trivial program that illustrates the use of @code{exit} and
 @code{atexit}:
 
-@example
-#include <stdio.h>
-#include <stdlib.h>
-
-void
-bye ()
-@{
-  printf ("Goodbye, cruel world....\n");
-@}
-
-void
-main ()
-@{
-  atexit (bye);
-  exit (EXIT_SUCCESS);
-@}
-@end example
+@smallexample
+@include atexit.c.texi
+@end smallexample
 
 @noindent
 When this program is executed, it just prints the message and exits.
@@ -803,8 +887,8 @@ for this function is in @file{stdlib.h}.
 @pindex stdlib.h
 
 @comment stdlib.h
-@comment ANSI
-@deftypefun void abort ()
+@comment ISO
+@deftypefun void abort (void)
 The @code{abort} function causes abnormal program termination.  This
 does not execute cleanup functions registered with @code{atexit} or
 @code{on_exit}.
@@ -812,15 +896,15 @@ does not execute cleanup functions registered with @code{atexit} or
 This function actually terminates the process by raising a
 @code{SIGABRT} signal, and your program can include a handler to
 intercept this signal; see @ref{Signal Handling}.
-
-@strong{Incomplete:}  Why would you want to define such a handler?
 @end deftypefun
 
-@c rms: I put this in.
+@c Put in by rms.  Don't remove.
+@cartouche
 @strong{Future Change Warning:} Proposed Federal censorship regulations
-may require us not to give you information about the possibility of
+may prohibit us from giving you information about the possibility of
 calling this function.  We would be required to say that this is not an
 acceptable way of terminating a program.
+@end cartouche
 
 @node Termination Internals
 @subsection Termination Internals
@@ -838,23 +922,39 @@ 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
+@comment stdlib.h
+@comment ISO
+@deftypefun void _Exit (int @var{status})
+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
-Input/Output}.
+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; 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
-parent process.  (This is the @code{init} process, with process ID 1.)
+parent process.  (On most systems, including GNU, this is the @code{init}
+process, with process ID 1.)
 
 @item
 A @code{SIGCHLD} signal is sent to the parent process.