Editing.
[kopensolaris-gnu/glibc.git] / manual / process.texi
index 883779c..c17c4b0 100644 (file)
@@ -1,5 +1,6 @@
-@node Child Processes, Job Control, Process Startup, Top
-@chapter Child Processes
+@node Processes, Job Control, Program Basics, Top
+@c %MENU% How to create processes and run other programs
+@chapter Processes
 
 @cindex process
 @dfn{Processes} are the primitive units for allocation of system
@@ -34,7 +35,7 @@ primitive functions to do each step individually instead.
 * Creating a Process::          How to fork a child process.
 * Executing a File::            How to make a process execute another program.
 * Process Completion::          How to tell when a child process has completed.
-* Process Completion Status::   How to interpret the status value 
+* Process Completion Status::   How to interpret the status value
                                  returned from a child process.
 * BSD Wait Functions::         More functions, for backward compatibility.
 * Process Creation Example::    A complete example program.
@@ -51,7 +52,7 @@ it doesn't give you much control over the details: you have to wait
 until the subprogram terminates before you can do anything else.
 
 @comment stdlib.h
-@comment ANSI
+@comment ISO
 @deftypefun int system (const char *@var{command})
 @pindex sh
 This function executes @var{command} as a shell command.  In the GNU C
@@ -62,6 +63,17 @@ possible to create the shell process, and otherwise is the status of the
 shell process.  @xref{Process Completion}, for details on how this
 status code can be interpreted.
 
+If the @var{command} argument is a null pointer, a return value of zero
+indicates that no command processor is available.
+
+This function is a cancellation point in multi-threaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{system} is
+called.  If the thread gets canceled these resources stay allocated
+until the program ends.  To avoid this calls to @code{system} should be
+protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+
 @pindex stdlib.h
 The @code{system} function is declared in the header file
 @file{stdlib.h}.
@@ -98,8 +110,8 @@ are freed.
 @cindex parent process
 Processes are created with the @code{fork} system call (so the operation
 of creating a new process is sometimes called @dfn{forking} a process).
-The @dfn{child process} created by @code{fork} is an exact clone of the
-original @dfn{parent process}, except that it has its own process ID.
+The @dfn{child process} created by @code{fork} is a copy of the original
+@dfn{parent process}, except that it has its own process ID.
 
 After forking a child process, both the parent and child processes
 continue to execute normally.  If you want your program to wait for a
@@ -179,7 +191,9 @@ defined for @code{fork}:
 @table @code
 @item EAGAIN
 There aren't enough system resources to create another process, or the
-user already has too many processes running.
+user already has too many processes running.  This means exceeding the
+@code{RLIMIT_NPROC} resource limit, which can usually be increased;
+@pxref{Limits on Resources}.
 
 @item ENOMEM
 The process requires more space than the system can supply.
@@ -201,7 +215,9 @@ parent process.
 The child process gets its own copies of the parent process's open file
 descriptors.  Subsequently changing attributes of the file descriptors
 in the parent process won't affect the file descriptors in the child,
-and vice versa.  @xref{Control Operations}.
+and vice versa.  @xref{Control Operations}.  However, the file position
+associated with each descriptor is shared by both processes;
+@pxref{File Position}.
 
 @item
 The elapsed processor times for the child process are set to zero;
@@ -209,6 +225,7 @@ see @ref{Processor Time}.
 
 @item
 The child doesn't inherit file locks set by the parent process.
+@c !!! flock locks shared
 @xref{Control Operations}.
 
 @item
@@ -219,21 +236,22 @@ The child doesn't inherit alarms set by the parent process.
 The set of pending signals (@pxref{Delivery of Signal}) for the child
 process is cleared.  (The child process inherits its mask of blocked
 signals and signal actions from the parent process.)
-@end itemize 
+@end itemize
 
 
 @comment unistd.h
 @comment BSD
 @deftypefun pid_t vfork (void)
-The @code{vfork} function is similar to @code{fork} but more efficient;
-however, there are restrictions you must follow to use it safely.
+The @code{vfork} function is similar to @code{fork} but on some systems
+it is more efficient; however, there are restrictions you must follow to
+use it safely.
 
 While @code{fork} makes a complete copy of the calling process's address
 space and allows both the parent and child to execute independently,
 @code{vfork} does not make this copy.  Instead, the child process
-created with @code{vfork} shares its parent's address space until it calls
-one of the @code{exec} functions.  In the meantime, the parent process
-suspends execution.
+created with @code{vfork} shares its parent's address space until it
+calls @code{_exit} or one of the @code{exec} functions.  In the
+meantime, the parent process suspends execution.
 
 You must be very careful not to allow the child process created with
 @code{vfork} to modify any global data or even local variables shared
@@ -258,6 +276,9 @@ This section describes the @code{exec} family of functions, for executing
 a file as a process image.  You can use these functions to make a child
 process execute a new program after it has been forked.
 
+To see the effects of @code{exec} from the point of view of the called
+program, @xref{Program Basics}.
+
 @pindex unistd.h
 The functions in this family differ in how you specify the arguments,
 but otherwise they all do the same thing.  They are declared in the
@@ -272,12 +293,13 @@ new process image.
 The @var{argv} argument is an array of null-terminated strings that is
 used to provide a value for the @code{argv} argument to the @code{main}
 function of the program to be executed.  The last element of this array
-must be a null pointer.  @xref{Program Arguments}, for information on
-how programs can access these arguments.
+must be a null pointer.  By convention, the first element of this array
+is the file name of the program sans directory names.  @xref{Program
+Arguments}, for full details on how programs can access these arguments.
 
 The environment for the new process image is taken from the
-@code{environ} variable of the current process image; see @ref{Environment
-Variables}, for information about environments.
+@code{environ} variable of the current process image; see
+@ref{Environment Variables}, for information about environments.
 @end deftypefun
 
 @comment unistd.h
@@ -293,7 +315,7 @@ passed as the last such argument.
 @deftypefun int execve (const char *@var{filename}, char *const @var{argv}@t{[]}, char *const @var{env}@t{[]})
 This is similar to @code{execv}, but permits you to specify the environment
 for the new program explicitly as the @var{env} argument.  This should
-be an array of strings in the same format as for the @code{environ} 
+be an array of strings in the same format as for the @code{environ}
 variable; see @ref{Environment Access}.
 @end deftypefun
 
@@ -338,7 +360,7 @@ rules for counting.
 These functions normally don't return, since execution of a new program
 causes the currently executing program to go away completely.  A value
 of @code{-1} is returned in the event of a failure.  In addition to the
-usual file name syntax errors (@pxref{File Name Errors}), the following
+usual file name errors (@pxref{File Name Errors}), the following
 @code{errno} error conditions are defined for these functions:
 
 @table @code
@@ -383,7 +405,10 @@ Persona}.
 Pending alarms.  @xref{Setting an Alarm}.
 
 @item
-Current working directory and root directory.  @xref{Working Directory}.
+Current working directory and root directory.  @xref{Working
+Directory}.  In the GNU system, the root directory is not copied when
+executing a setuid program; instead the system default root directory
+is used for the new program.
 
 @item
 File mode creation mask.  @xref{Setting Permissions}.
@@ -419,12 +444,9 @@ because they are located in the memory of the process itself.  The new
 process image has no streams except those it creates afresh.  Each of
 the streams in the pre-@code{exec} process image has a descriptor inside
 it, and these descriptors do survive through @code{exec} (provided that
-they do not have @code{FD_CLOEXEC} set.  The new process image can
+they do not have @code{FD_CLOEXEC} set).  The new process image can
 reconnect these to new streams using @code{fdopen} (@pxref{Descriptors
 and Streams}).
-@c ??? this is a bad thing to recommend.  it won't work in GNU, where
-@c fopen doesn't go thru a file descriptor.
-@c ??? I think Posix.1 requires this to work -- rms.
 
 @node Process Completion
 @section Process Completion
@@ -439,7 +461,7 @@ are declared in the header file @file{sys/wait.h}.
 
 @comment sys/wait.h
 @comment POSIX.1
-@deftypefun pid_t waitpid (pid_t @var{pid}, int *@var{status_ptr}, int @var{options})
+@deftypefun pid_t waitpid (pid_t @var{pid}, int *@var{status-ptr}, int @var{options})
 The @code{waitpid} function is used to request status information from a
 child process whose process ID is @var{pid}.  Normally, the calling
 process is suspended until the child process makes status information
@@ -468,13 +490,29 @@ and the @code{WUNTRACED} flag to request status information from stopped
 processes as well as processes that have terminated.
 
 The status information from the child process is stored in the object
-that @var{status_ptr} points to, unless @var{status_ptr} is a null pointer.
+that @var{status-ptr} points to, unless @var{status-ptr} is a null pointer.
+
+This function is a cancellation point in multi-threaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{waitpid} is
+called.  If the thread gets canceled these resources stay allocated
+until the program ends.  To avoid this calls to @code{waitpid} should be
+protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
 
 The return value is normally the process ID of the child process whose
-status is reported.  If the @code{WNOHANG} option was specified and no
-child process is waiting to be noticed, the value is zero.  A value of
-@code{-1} is returned in case of error.  The following @code{errno}
-error conditions are defined for this function:
+status is reported.  If there are child processes but none of them is
+waiting to be noticed, @code{waitpid} will block until one is.  However,
+if the @code{WNOHANG} option was specified, @code{waitpid} will return
+zero instead of blocking.
+
+If a specific PID to wait for was given to @code{waitpid}, it will
+ignore all other children (if any).  Therefore if there are children
+waiting to be noticed but the child whose PID was specified is not one
+of them, @code{waitpid} will block or return zero as described above.
+
+A value of @code{-1} is returned in case of error.  The following
+@code{errno} error conditions are defined for this function:
 
 @table @code
 @item EINTR
@@ -526,20 +564,41 @@ terminated.
 
 @comment sys/wait.h
 @comment POSIX.1
-@deftypefun pid_t wait (int *@var{status_ptr})
+@deftypefun pid_t wait (int *@var{status-ptr})
 This is a simplified version of @code{waitpid}, and is used to wait
 until any one child process terminates.  The call:
 
-@example
+@smallexample
 wait (&status)
-@end example
+@end smallexample
 
 @noindent
 is exactly equivalent to:
 
-@example
+@smallexample
 waitpid (-1, &status, 0)
-@end example
+@end smallexample
+
+This function is a cancellation point in multi-threaded programs.  This
+is a problem if the thread allocates some resources (like memory, file
+descriptors, semaphores or whatever) at the time @code{wait} is
+called.  If the thread gets canceled these resources stay allocated
+until the program ends.  To avoid this calls to @code{wait} should be
+protected using cancellation handlers.
+@c ref pthread_cleanup_push / pthread_cleanup_pop
+@end deftypefun
+
+@comment sys/wait.h
+@comment BSD
+@deftypefun pid_t wait4 (pid_t @var{pid}, int *@var{status-ptr}, int @var{options}, struct rusage *@var{usage})
+If @var{usage} is a null pointer, @code{wait4} is equivalent to
+@code{waitpid (@var{pid}, @var{status-ptr}, @var{options})}.
+
+If @var{usage} is not null, @code{wait4} stores usage figures for the
+child process in @code{*@var{rusage}} (but only if the child has
+terminated, not if it has stopped).  @xref{Resource Usage}.
+
+This function is a BSD extension.
 @end deftypefun
 
 Here's an example of how to use @code{waitpid} to get the status from
@@ -547,13 +606,13 @@ all child processes that have terminated, without ever waiting.  This
 function is designed to be a handler for @code{SIGCHLD}, the signal that
 indicates that at least one child process has terminated.
 
-@example
+@smallexample
 @group
 void
 sigchld_handler (int signum)
 @{
-  int pid;
-  int status;
+  int pid, status, serrno;
+  serrno = errno;
   while (1)
     @{
       pid = waitpid (WAIT_ANY, &status, WNOHANG);
@@ -566,9 +625,10 @@ sigchld_handler (int signum)
         break;
       notice_termination (pid, status);
     @}
+  errno = serrno;
 @}
 @end group
-@end example
+@end smallexample
 
 @node Process Completion Status
 @section Process Completion Status
@@ -640,7 +700,7 @@ status values rather than an @code{int}.  The two representations are
 actually interchangeable; they describe the same bit patterns.  The GNU
 C Library defines macros such as @code{WEXITSTATUS} so that they will
 work on either kind of object, and the @code{wait} function is defined
-to accept either type of pointer as its @var{status_ptr} argument.
+to accept either type of pointer as its @var{status-ptr} argument.
 
 These functions are declared in @file{sys/wait.h}.
 @pindex sys/wait.h
@@ -653,44 +713,40 @@ the following members:
 
 @table @code
 @item int w_termsig
-This member is equivalent to the @code{WTERMSIG} macro.
+The value of this member is the same as that of the
+@code{WTERMSIG} macro.
 
 @item int w_coredump
-This member is equivalent to the @code{WCOREDUMP} macro.
+The value of this member is the same as that of the
+@code{WCOREDUMP} macro.
 
 @item int w_retcode
-This member is equivalent to the @code{WEXISTATUS} macro.
+The value of this member is the same as that of the
+@code{WEXITSTATUS} macro.
 
 @item int w_stopsig
-This member is equivalent to the @code{WSTOPSIG} macro.
+The value of this member is the same as that of the
+@code{WSTOPSIG} macro.
 @end table
 
 Instead of accessing these members directly, you should use the
 equivalent macros.
 @end deftp
 
+The @code{wait3} function is the predecessor to @code{wait4}, which is
+more flexible.  @code{wait3} is now obsolete.
+
 @comment sys/wait.h
 @comment BSD
-@deftypefun pid_t wait3 (union wait *@var{status_ptr}, int @var{options}, struct rusage *@var{usage})
+@deftypefun pid_t wait3 (union wait *@var{status-ptr}, int @var{options}, struct rusage *@var{usage})
 If @var{usage} is a null pointer, @code{wait3} is equivalent to
-@w{@code{waitpid (-1, @var{status_ptr}, @var{options})}}.
+@code{waitpid (-1, @var{status-ptr}, @var{options})}.
 
 If @var{usage} is not null, @code{wait3} stores usage figures for the
 child process in @code{*@var{rusage}} (but only if the child has
 terminated, not if it has stopped).  @xref{Resource Usage}.
 @end deftypefun
 
-@comment sys/wait.h
-@comment BSD
-@deftypefun pid_t wait4 (pid_t @var{pid}, union wait *@var{status_ptr}, int @var{options}, struct rusage *@var{usage})
-If @var{usage} is a null pointer, @code{wait4} is equivalent to
-@w{@code{waitpid (@var{pid}, @var{status_ptr}, @var{options})}}.
-
-If @var{usage} is not null, @code{wait4} stores usage figures for the
-child process in @code{*@var{rusage}} (but only if the child has
-terminated, not if it has stopped).  @xref{Resource Usage}.
-@end deftypefun
-
 @node Process Creation Example
 @section Process Creation Example
 
@@ -698,7 +754,7 @@ Here is an example program showing how you might write a function
 similar to the built-in @code{system}.  It executes its @var{command}
 argument using the equivalent of @samp{sh -c @var{command}}.
 
-@example
+@smallexample
 #include <stddef.h>
 #include <stdlib.h>
 #include <unistd.h>
@@ -709,7 +765,7 @@ argument using the equivalent of @samp{sh -c @var{command}}.
 #define SHELL "/bin/sh"
 
 @group
-int 
+int
 my_system (const char *command)
 @{
   int status;
@@ -732,7 +788,7 @@ my_system (const char *command)
       status = -1;
   return status;
 @}
-@end example
+@end smallexample
 
 @comment Yes, this example has been tested.
 
@@ -742,7 +798,7 @@ example.
 Remember that the first @code{argv} argument supplied to the program
 represents the name of the program being executed.  That is why, in the
 call to @code{execl}, @code{SHELL} is supplied once to name the program
-to execute and a second time to supply a value for @code{argv[0]}.  
+to execute and a second time to supply a value for @code{argv[0]}.
 
 The @code{execl} call in the child process doesn't return if it is
 successful.  If it fails, you must do something to make the child