(grow_heap): When growing bail even if new_size is negative.
[kopensolaris-gnu/glibc.git] / manual / startup.texi
index e61a755..5ccb78b 100644 (file)
@@ -1,24 +1,43 @@
-@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 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 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.
+* 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
@@ -67,11 +86,11 @@ three elements, @code{"cat"}, @code{"foo"} and @code{"bar"}.
 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}.
@@ -81,7 +100,7 @@ allow this three-argument form, so to be portable it is best to write
 * 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
@@ -102,7 +121,7 @@ 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
@@ -153,7 +172,7 @@ accept an argument that is itself optional.
 Eventually, the GNU system will provide completion for long option names
 in the shell.
 
-@node Parsing Program Arguments
+@node Parsing Program Arguments, , Argument Syntax, Program Arguments
 @subsection Parsing Program Arguments
 
 @cindex program arguments, parsing
@@ -187,7 +206,7 @@ it does more of the dirty work for you.
 
 @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
-@section Parsing of Suboptions
+@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
@@ -278,9 +297,9 @@ character, since this is assumed to terminate the string.
 
 @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
@@ -290,7 +309,9 @@ 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
@@ -307,23 +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
 
-@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
@@ -356,7 +439,7 @@ 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
@@ -372,18 +455,18 @@ 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
+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
@@ -410,7 +493,7 @@ 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
@@ -420,13 +503,13 @@ of terminals.  Many programs which use the termcap library
 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
@@ -436,7 +519,7 @@ 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
@@ -444,34 +527,54 @@ 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} and
@@ -480,6 +583,113 @@ reordering of command line arguments by @code{getopt} and
 @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
@@ -513,15 +723,19 @@ a signal that kills the program.
 @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.
+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:
@@ -613,6 +827,12 @@ kinds of "non-success".  For example, @code{diff} uses status value
 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
 
@@ -702,20 +922,34 @@ 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 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