Editing.
[kopensolaris-gnu/glibc.git] / manual / process.texi
index 472c33c..c17c4b0 100644 (file)
@@ -1,4 +1,5 @@
-@node Processes
+@node Processes, Job Control, Program Basics, Top
+@c %MENU% How to create processes and run other programs
 @chapter Processes
 
 @cindex process
@@ -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}.
@@ -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.
@@ -222,21 +236,21 @@ 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 on systems it
-is more efficient; however, there are restrictions you must follow to
+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 exits or one of the @code{exec} functions.  In the
+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 @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
@@ -262,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
@@ -298,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
 
@@ -343,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
@@ -475,11 +492,27 @@ 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.
 
+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
@@ -545,6 +578,27 @@ is exactly equivalent to:
 @smallexample
 waitpid (-1, &status, 0)
 @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
@@ -557,8 +611,8 @@ indicates that at least one child process has terminated.
 void
 sigchld_handler (int signum)
 @{
-  int pid;
-  int status;
+  int pid, status, serrno;
+  serrno = errno;
   while (1)
     @{
       pid = waitpid (WAIT_ANY, &status, WNOHANG);
@@ -571,6 +625,7 @@ sigchld_handler (int signum)
         break;
       notice_termination (pid, status);
     @}
+  errno = serrno;
 @}
 @end group
 @end smallexample
@@ -658,19 +713,19 @@ the following members:
 
 @table @code
 @item int w_termsig
-The value of this member is the same as the result of the
+The value of this member is the same as that of the
 @code{WTERMSIG} macro.
 
 @item int w_coredump
-The value of this member is the same as the result of the
+The value of this member is the same as that of the
 @code{WCOREDUMP} macro.
 
 @item int w_retcode
-The value of this member is the same as the result of the
+The value of this member is the same as that of the
 @code{WEXITSTATUS} macro.
 
 @item int w_stopsig
-The value of this member is the same as the result of the
+The value of this member is the same as that of the
 @code{WSTOPSIG} macro.
 @end table
 
@@ -678,6 +733,9 @@ 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})
@@ -689,17 +747,6 @@ 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
-@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
 
@@ -718,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;
@@ -751,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