Editing.
[kopensolaris-gnu/glibc.git] / manual / process.texi
index 4b76f9d..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}.
@@ -224,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
@@ -264,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
@@ -300,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
 
@@ -345,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
@@ -477,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
@@ -547,6 +578,14 @@ 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
@@ -572,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);
@@ -586,6 +625,7 @@ sigchld_handler (int signum)
         break;
       notice_termination (pid, status);
     @}
+  errno = serrno;
 @}
 @end group
 @end smallexample
@@ -673,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
 
@@ -725,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;
@@ -758,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