(grow_heap): When growing bail even if new_size is negative.
[kopensolaris-gnu/glibc.git] / manual / startup.texi
index 1d903b4..5ccb78b 100644 (file)
@@ -1,25 +1,43 @@
-@node Process Startup, Processes, Signal Handling, Top
+@node Program Basics, Processes, Signal Handling, Top
 @c %MENU% Writing the beginning and end of your program
-@chapter Process Startup and Termination
+@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
@@ -68,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}.
@@ -310,13 +328,21 @@ 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 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.
@@ -329,31 +355,34 @@ available in old SVID libraries you should define either
 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.  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.
+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 is part of the BSD library.  The GNU C Library provides
-this function for compatibility but it may not be available on other
-systems.
+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 void unsetenv (const char *@var{name})
+@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.
 
-This function is part of the BSD library.  The GNU C Library provides
-this function for compatibility but it may not be available on other
-systems.
+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
@@ -430,7 +459,7 @@ this lets the user specify the value.
 
 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
@@ -554,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
@@ -587,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:
@@ -687,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
 
@@ -776,8 +922,20 @@ 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
@@ -787,9 +945,11 @@ 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