Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
wait(2)			      System Calls Manual		       wait(2)

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

SYNOPSIS
DESCRIPTION
       The  and	 functions allow the calling process to	obtain status informa-
       tion pertaining to one of its child processes. Various options	permit
       status  information to be obtained for child processes that have	termi-
       nated or	stopped. If status information is available for	 two  or  more
       child processes,	the order in which their status	is reported is unspec-
       ified.

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

       The function  will  behave  identically	to  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  function  will  only  return the status of a child
       process from this set:

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

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

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

	      o	 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

	      The		       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.

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

	      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 set or has set to and	the process has	no un-
       waited  for  children  that  were transformed into zombie processes, it
       will block until	all of its children terminate, and and will  fail  and
       set to

       If  or 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 or passed 0 as the  status  argument
       to  or  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 and evaluate to integral ex-
       pressions; the stat_val argument	is the integer	value  pointed	to  by
       stat_loc.

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

	      If the value of	       is non-zero, this  macro	 evaluates  to
				       the  low-order 8	bits of	the status ar-
				       gument that the child process passed to
				       or  or the value	the child  process re-
				       turned from

	      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>).

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

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

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

	      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  that
       specified  the  flag  and  did not specify the flag, exactly one	of the
       macros and will evaluate	to a non-zero value.

       If the information pointed to by	stat_loc was stored by a call to  that
       specified the and flags,	exactly	one of the macros and will evaluate to
       a non-zero value.

       If the information pointed to by	stat_loc was stored by a call to  that
       did not specify the or flags, or	by a call to the function, exactly one
       of the  macros and will evaluate	to a non-zero value.

       If the information pointed to by	stat_loc was stored by a call to  that
       did not specify the flag	and specified the flag,	by a call to the func-
       tion, exactly one of the	macros and will	evaluate to a non-zero value.

       There may be additional	implementation-dependent  circumstances	 under
       which  or report	status.	This will not occur unless the calling process
       or one of its child processes explicitly	makes use  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 or 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	or returns due to the delivery
       of a signal to the calling process, -1 will be returned and will	be set
       to  If  was  invoked  with  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 will be set to indicate  the
       error.

ERRORS
       The 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 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 or

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

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:

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

       Other changes are incorporated as follows:

	      o	 The  header is	now marked as optional (OH); this header  need
		 not be	included on XSI-conformant systems.

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

	      o	 The  words  "If  the implementation supports job control" are
		 removed from the description of This is because  job  control
		 is  defined  as  mandatory for	Issue 4	conforming implementa-
		 tions.

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

	      o	 The options flag and the macro	are added.

	      o	 Text  following the list of options flags explains the	impli-
		 cations of setting the	signal flag, or	setting	to

	      o	 Text following	the list of macros, which explains what	macros
		 return	 non-zero values in certain cases, is expanded and the
		 value of the flag on the previous call	to is taken  into  ac-
		 count.

wait(2)			      System Calls Manual		       wait(2)

				  HP-UX	EXTENSIONS

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

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.

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

waitpid()
	      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.

	      If and only if this flag is set,
				       or returns information on child or  at-
				       tached  processes  that are stopped but
				       not traced (with	because	they  received
				       a  or  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  re-
       turned  by  rather than the macros and Applications using those bit en-
       codings will continue to	work  correctly.   However,  new  applications
       should use the macros for maximum portability.

       In  earlier HP-UX versions, the macros and have the same	definitions as
       the correspondingly named macros	in the BSD 4.3	and  earlier  systems.
       Existing	applications that depend on these definitions will continue to
       work correctly. However,	if the application is recompiled, the  feature
       test  macro must	be turned on for the compilation so that the old defi-
       nitions 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 is used in the  BSD
       definitions while type int is used in the default definitions.

ERRORS
       If or fails, is set to one of the following values.

	      The calling process of   does  not  have	read permission	to the
				       pid.

	      stat_loc		       points to an illegal address. The reli-
				       able  detection of this error is	imple-
				       mentation-dependent.

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

AUTHOR
       wait(), waitpid(), and wait3() were developed by	HP, AT&T, and the Uni-
       versity 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

								       wait(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | APPLICATION USAGE | SEE ALSO | CHANGE HISTORY | Issue 4 | Issue 4, Version 2 | NAME | DESCRIPTION | wait() | waitpid() | Notes | ERRORS | WARNINGS | AUTHOR | SEE ALSO | STANDARDS CONFORMANCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=wait&sektion=2&manpath=HP-UX+11.22>

home | help