unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 wait(2)							     wait(2)




 NAME
      wait, waitpid - wait for child process to stop or terminate

 SYNOPSIS
      #include <&lt&lt&lt;sys/types.h>&gt&gt&gt;   OH
      #include <&lt&lt&lt;sys/wait.h>&gt&gt&gt;

      pid_t wait(int *stat_loc);

      pid_t waitpid(pid_t pid, int *stat_loc, int options);

 DESCRIPTION
      The wait() and waitpid() functions allow the calling process to obtain
      status information pertaining to one of its child processes. Various
      options  permit status information to be obtained for child processes
      that have terminated or stopped. If status information is available
      for two or more child processes, the order in which their status is
      reported is unspecified.

      The wait() function will suspend execution of the calling	 process
      until status information for one of its terminated child processes is
      available, or until delivery of a signal whose action is either to
      execute a signal-catching function or to terminate the process. If
      status information is available prior to the call to wait(), return
      will be immediate.

      The waitpid() function will behave identically to wait(), if the pid
      argument is (pid_t)-1 and the options argument is	 0. Otherwise, its
      behaviour will be modified by the values of the pid and options
      arguments.

      The pid argument specifies a set of child	 processes for which status
      is requested. The waitpid() function will only return the status of a
      child process from this set:

	   +  If pid is equal to (pid_t)-1, status is requested for any
	      child process. In this respect, waitpid() is then equivalent
	      to wait().

	   +  If pid is greater	 than  0,  it  specifies  the process  ID of
	      a single child process for which status is requested.

	   +  If pid is 0, status is requested for any	child process whose
	      process group ID is equal to that of the calling process.

	   +  If pid is less than (pid_t)-1, status is requested for any
	      child process whose process group ID is equal to the absolute
	      value of pid.

      The options argument is constructed from the bitwise-inclusive OR of
      zero or more of the following flags, defined in the header



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 wait(2)							     wait(2)




      <&lt&lt&lt;sys/wait.h>&gt&gt&gt;.

	   WCONTINUED		    The waitpid() function will report the
				    status of any continued child process
				    specified by pid whose status has not
				    been reported since it continued from a
				    job control stop.

	   WNOHANG		    The waitpid() function will not suspend
				    execution of the calling process if
				    status is not immediately available for
				    one of the child processes specified by
				    pid.

	   WUNTRACED		    The status of any child processes
				    specified by pid that are stopped, and
				    whose status has not yet been reported
				    since they stopped, will also be
				    reported to the requesting process.

      If the calling process has SA_NOCLDWAIT set or has SIGCHLD set to
      SIG_IGN, and the process has no unwaited for children that were
      transformed into zombie processes, it will block until all of its
      children terminate, and wait() and waitpid() will fail and set errno
      to ECHILD.

      If wait() or waitpid() return because the status of a child process is
      available, these functions will return a value equal to the process ID
      of the child process. In this case, if the value of the argument
      stat_loc is not a null pointer, information will be stored in the
      location pointed to by stat_loc.	If and only if the status returned
      is from a terminated child process that returned 0 from main() or
      passed 0 as the status argument to _exit() or exit(), the value stored
      at the location pointed to by stat_loc will be 0. Regardless of its
      value, this information may be interpreted using the following macros,
      which are defined in <&lt&lt&lt;sys/wait.h>&gt&gt&gt; and evaluate to integral
      expressions; the stat_val argument is the integer value pointed to by
      stat_loc.

	   WIFEXITED(stat_val)	    Evaluates to a non-zero value if status
				    was returned for a child process that
				    terminated normally.

	   WEXITSTATUS(stat_val)    If the value of WIFEXITED(stat_val) is
				    non-zero, this macro evaluates to the
				    low-order 8 bits of the status argument
				    that the child process passed to _exit()
				    or exit(), or the value the child
				    process returned from main().





 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 wait(2)							     wait(2)




	   WIFSIGNALED(stat_val)    Evaluates to non-zero value if status
				    was returned for a child process that
				    terminated due to the receipt of a
				    signal that was not caught (see
				    <signal.h>).

	   WTERMSIG(stat_val)	    If the value of WIFSIGNALED(stat_val) is
				    non-zero, this macro evaluates to the
				    number of the signal that caused the
				    termination of the child process.

	   WIFSTOPPED(stat_val)	    Evaluates to a non-zero value if status
				    was returned for a child process that is
				    currently stopped.

	   WSTOPSIG(stat_val)	    If the value of WIFSTOPPED(stat_val) is
				    non-zero, this macro evaluates to the
				    number of the signal that caused the
				    child process to stop.

	   WIFCONTINUED(stat_val)   Evaluates to a non-zero value if status
				    was returned for a child process that
				    has continued from a job control stop.

      If the information pointed to by stat_loc was stored by a call to
      waitpid() that specified the WUNTRACED flag and did not specify the
      WCONTINUED flag, exactly one of the macros WIFEXITED(*stat_loc),
      WIFSIGNALED(*stat_loc), and WIFSTOPPED(*stat_loc) will evaluate to a
      non-zero value.

      If the information pointed to by stat_loc was stored by a call to
      waitpid() that specified the WUNTRACED and WCONTINUED flags, exactly
      one of the macros WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc),
      WIFSTOPPED(*stat_loc), and WIFCONTINUED (*stat_loc) will evaluate to a
      non-zero value.

      If the information pointed to by stat_loc was stored by a call to
      waitpid() that did not specify the WUNTRACED or WCONTINUED flags, or
      by a call to the wait() function, exactly one of the  macros
      WIFEXITED(*stat_loc) and WIFSIGNALED(*stat_loc) will evaluate to a
      non-zero value.

      If the information pointed to by stat_loc was stored by a call to
      waitpid() that did not specify the WUNTRACED flag and specified the
      WCONTINUED flag, by a call to the wait() function, exactly one of the
      macros WIFEXITED(*stat_loc), WIFSIGNALED(*stat_loc), and
      WIFCONTINUED(*stat_loc) will evaluate to a non-zero value.

      There may be additional implementation-dependent circumstances under
      which wait() or waitpid() report status. This will not occur unless
      the calling process or one of its child processes explicitly makes use



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 wait(2)							     wait(2)




      of a non-standard extension. In  these cases the interpretation of the
      reported status is implementation-dependent.

      If a parent process terminates without waiting for all of its child
      processes to terminate, the remaining child processes will be assigned
      a new parent process ID corresponding to an implementation-dependent
      system process.

 RETURN VALUE
      If wait() or waitpid() returns because the status of a child process
      is available, these functions will return a value equal to the process
      ID of the	 child process for which status is reported. If wait() or
      waitpid() returns due to the delivery of a signal to the calling
      process, -1 will be returned and errno will be set to EINTR.  If
      waitpid() was invoked with WNOHANG set in options, it has at least one
      child process specified by pid for which status is not available, and
      status is not available for any process specified by pid, 0 will be
      returned. Otherwise, (pid_t)-1 will be returned, and errno will be set
      to indicate the error.

 ERRORS
      The wait() function will fail if:

      [ECHILD]	     The calling process has no existing unwaited-for child
		     processes.

      [EINTR]	     The function was interrupted by a signal. The value of
		     the location pointed to by stat_loc is undefined.

      The waitpid() function will fail if:

      [ECHILD]	     The process or process group specified by pid does not
		     exist or is not a child of the calling process.

      [EINTR]	     The function was interrupted by a signal. The value of
		     the location pointed to by stat_loc is undefined.

      [EINVAL]	     The options argument is not valid.

 APPLICATION USAGE
    Threads Considerations
      In a multi-threaded application, only the calling thread is suspended
      by wait() or waitpid().

      wait() and waitpid() will not return until all threads in the process
      have reached the desired state.  For example, wait() and waitpid()
      will not return until all threads have terminated.  If the WUNTRACED
      or WCONTINUED options are specified for waitpid(), the function will
      not return until all threads have stopped or continued respectively.





 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 wait(2)							     wait(2)




 SEE ALSO
      exec(2), exit(2), fork(2), wait3(2), waitid(2), <sys/types.h>,
      <sys/wait.h>.

 CHANGE HISTORY
      First released in Issue 1.

      Derived from Issue 1 of the SVID.

 Issue 4
      The following change is incorporated for alignment with the ISO
      POSIX-1 standard:

	   +  Text describing conditions under which 0 will be returned when
	      WNOHANG is set in options is added to the RETURN VALUE
	      section.

      Other changes are incorporated as follows:

	   +  The  header <&lt&lt&lt;sys/types.h>&gt&gt&gt; is now marked as optional (OH); this
	      header need not be included on XSI-conformant systems.

	   +  Error return values throughout the  DESCRIPTION and  RETURN
	      VALUE sections are changed to show the proper casting (that
	      is, (pid_t)-1.

	   +  The words "If the implementation supports job control" are
	      removed from the description of WUNTRACED.  This is because
	      job control is defined as mandatory for Issue 4 conforming
	      implementations.

 Issue 4, Version 2
      The following changes are incorporated in the DESCRIPTION for X/OPEN
      UNIX conformance:

	   +  The WCONTINUED options flag and the WIFCONTINUED(stat_val)
	      macro are added.

	   +  Text following the list of options flags explains the
	      implications of setting the SA_NOCLDWAIT signal flag, or
	      setting SIGCHILD to SIG_IGN.

	   +  Text following the list of macros, which explains what macros
	      return non-zero values in certain cases, is expanded and the
	      value of the WCONTINUED flag on the previous call to waitpid()
	      is taken into account.








				    - 5 -	  Formatted:  August 2, 2006






 wait(2)							     wait(2)




				 HP-UX EXTENSIONS



 NAME
      wait(), waitpid() - wait for child or traced process to stop or
      terminate

 DESCRIPTION
 wait()
      If a parent process terminates without waiting for its child processes
      to terminate, the parent process ID of each child process is set to 1.
      This means the initialization process inherits the child processes.

	   WCOREDUMP(*stat_loc)	    If the value of WIFSIGNALED(*stat_loc)
				    is nonzero, this macro evaluates to a
				    nonzero value if a "core image" was
				    produced (see signal(5)).

 waitpid()
	   WNOWAIT		    Keep the process whose status is
				    returned in *stat_loc in a waitable
				    state. The process may be waited for
				    again with identical results, provided
				    the state of the process doesn't change
				    in the interim.

	   WUNTRACED		    If and only if this flag is set,
				    waitpid() or wait3() returns information
				    on child or attached processes that are
				    stopped but not traced (with ptrace())
				    because they received a SIGTTIN,
				    SIGTTOU, SIGTSTP, or SIGSTOP signal, and
				    whose status has not yet been reported.
				    Regardless of this flag, status is
				    returned for child or attached processes
				    that have terminated or are stopped and
				    traced and whose status has not yet been
				    reported.

 Notes
      Earlier HP-UX versions documented the bit encodings of the status
      returned by wait() rather than the macros WCOREDUMP, WEXITSTATUS,
      WIFEXITED, WIFSIGNALED, WIFSTOPPED, WSTOPSIG, and WTERMSIG.
      Applications using those bit encodings will continue to work
      correctly.  However, new applications should use the macros for
      maximum portability.

      In earlier HP-UX versions, the macros WIFEXITED, WIFSIGNALED, and
      WIFSTOPPED have the same definitions as the correspondingly named
      macros in the BSD 4.3 and earlier systems. Existing applications that



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 wait(2)							     wait(2)




      depend on these definitions will continue to work correctly. However,
      if the application is recompiled, the feature test macro _BSD must be
      turned on for the compilation so that the old definitions of these
      macros are obtained. New definitions of these macros are in effect by
      default. The only difference between the old and new definitions is
      the type of the argument. Type union wait is used in the BSD
      definitions while type int is used in the default definitions.

 ERRORS
      If wait() or waitpid() fails, errno is set to one of the following
      values.

	   [EACCES]		    The calling process of waitpid() does
				    not have read permission to the pid.

	   [EFAULT]		    stat_loc points to an illegal address.
				    The reliable detection of this error is
				    implementation-dependent.

 WARNINGS
      The behavior of wait() and waitpid() is affected if the SIGCLD signal
      is set to SIG_IGN.  See the WARNINGS section of signal(5).  Signal
      handlers that cause system calls to be restarted can affect the EINTR
      condition described above (see bsdproc(3C), sigaction(2), and
      sigvector(2)).

 AUTHOR
      wait(), waitpid(), and wait3() were developed by HP, AT&T, and the
      University of California, Berkeley.

 SEE ALSO
      Exit conditions ($?) in sh(1); exec(2), exit(2), fork(2), pause(2),
      ptrace(2), signal(5).

 STANDARDS CONFORMANCE
      wait(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

      waitpid(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1
















 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000