Date: Thu, 13 Dec 2012 06:27:59 +0000 (UTC) From: Konstantin Belousov <kib@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-9@freebsd.org Subject: svn commit: r244176 - stable/9/lib/libc/sys Message-ID: <201212130627.qBD6RxvA063091@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: kib Date: Thu Dec 13 06:27:58 2012 New Revision: 244176 URL: http://svnweb.freebsd.org/changeset/base/244176 Log: MFC r242961: Document wait6() and waitid(). PR: standards/170346 Modified: stable/9/lib/libc/sys/Makefile.inc stable/9/lib/libc/sys/wait.2 Directory Properties: stable/9/lib/libc/ (props changed) stable/9/lib/libc/sys/ (props changed) Modified: stable/9/lib/libc/sys/Makefile.inc ============================================================================== --- stable/9/lib/libc/sys/Makefile.inc Thu Dec 13 06:24:54 2012 (r244175) +++ stable/9/lib/libc/sys/Makefile.inc Thu Dec 13 06:27:58 2012 (r244176) @@ -214,5 +214,6 @@ MLINKS+=timer_settime.2 timer_getoverrun MLINKS+=truncate.2 ftruncate.2 MLINKS+=unlink.2 unlinkat.2 MLINKS+=utimes.2 futimes.2 utimes.2 futimesat.2 utimes.2 lutimes.2 -MLINKS+=wait.2 wait3.2 wait.2 wait4.2 wait.2 waitpid.2 +MLINKS+=wait.2 wait3.2 wait.2 wait4.2 wait.2 waitpid.2 \ + wait.2 waitid.2 wait.2 wait6.2 MLINKS+=write.2 pwrite.2 write.2 pwritev.2 write.2 writev.2 Modified: stable/9/lib/libc/sys/wait.2 ============================================================================== --- stable/9/lib/libc/sys/wait.2 Thu Dec 13 06:24:54 2012 (r244175) +++ stable/9/lib/libc/sys/wait.2 Thu Dec 13 06:27:58 2012 (r244176) @@ -28,15 +28,17 @@ .\" @(#)wait.2 8.2 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" -.Dd November 12, 2005 +.Dd November 10, 2012 .Dt WAIT 2 .Os .Sh NAME .Nm wait , +.Nm waitid , .Nm waitpid , +.Nm wait3 , .Nm wait4 , -.Nm wait3 -.Nd wait for process termination +.Nm wait6 +.Nd wait for processes to change status .Sh LIBRARY .Lb libc .Sh SYNOPSIS @@ -46,12 +48,17 @@ .Fn wait "int *status" .Ft pid_t .Fn waitpid "pid_t wpid" "int *status" "int options" +.In sys/signal.h +.Ft int +.Fn waitid "idtype_t idtype" "id_t id" "siginfo_t *info" "int options" .In sys/time.h .In sys/resource.h .Ft pid_t .Fn wait3 "int *status" "int options" "struct rusage *rusage" .Ft pid_t .Fn wait4 "pid_t wpid" "int *status" "int options" "struct rusage *rusage" +.Ft pid_t +.Fn wait6 "idtype_t idtype" "id_t id" "int *status" "int options" "struct __wrusage *wrusage" "siginfo_t *infop" .Sh DESCRIPTION The .Fn wait @@ -86,28 +93,172 @@ system call provides a more general inte that need to wait for certain child processes, that need resource utilization statistics accumulated by child processes, or that require options. -The other wait functions are implemented using -.Fn wait4 . .Pp -The +The broadest interface of all functions in this family is +.Fn wait6 +which is otherwise very much like +.Fn wait4 +but with a few very important distinctions. +To wait for exited processes, the option flag +.Dv WEXITED +need to be explicitly specified. +This allows for waiting for processes which have experienced other +status changes without having to handle also the exit status from +the terminated processes. +Instead of the traditional +.Dv rusage +argument, a pointer to a new structure +.Bd -literal +struct __wrusage { + struct rusage wru_self; + struct rusage wru_children; +}; +.Ed +can be passed. +This allows the calling process to collect resource usage statistics +from both its own child process as well as from its grand children. +When no resource usage statistics are needed this pointer can be +.Dv NULL . +The last argument +.Fa infop +must be either +.Dv NULL +or a pointer to a +.Fa siginfo_t +structure. +When specified, the structure is filled the same as for +.Dv SIGNCHLD +signal, delivered at the process state change. +.br +The process, which state is queried, is specified by two arguments +.Fa idtype +and +.Fa id . +The separate +.Fa idtype +and +.Fa id +arguments allows to support many other types of +IDs as well in addition to PID and PGID. +.Bl -bullet -offset indent +.It +If +.Fa idtype +is +.Dv P_PID , +.Fn waitid +and +.Fn wait6 +wait for the child process with a process ID equal to +.Dv (pid_t)id . +.It +If +.Fa idtype +is +.Dv P_PGID , +.Fn waitid +and +.Fn wait6 +wait for the child process with a process group ID equal to +.Dv (pid_t)id . +.It +If +.Fa idtype +is +.Dv P_ALL , +.Fn waitid +and +.Fn wait6 +wait for any child process and the +.Dv id +is ignored. +.It +If +.Fa idtype +is +.Dv P_PID +or +.Dv P_PGID +and the +.Dv id +is zero, +.Fn waitid +and +.Fn wait6 +wait for any child process in the same process group as the caller. +.El +.Pp +Non-standard specifiers for the process to wait for, supported by this +implementation of +.Fn waitid +and +.Fn wait6 , +are: +.Bl -bullet -offset indent +.It +The +.Fa idtype +value +.Dv P_UID +waits for processes which effective UID is equal to +.Dv (uid_t)id . +.It +The +.Fa idtype +value +.Dv P_GID +waits for processes which effective GID is equal to +.Dv (gid_t)id . +.It +The +.Fa idtype +value +.Dv P_SID +waits for processes which session ID is equal to +.Dv id . +In case the child process started its own new session, +SID will be the same as its own PID. +Otherwise the SID of a child process will match the caller's SID. +.It +The +.Fa idtype +value +.Dv P_JAILID +waits for processes within a jail which jail identifier is equal +to +.Dv id . +.El +.Pp +For +.Fn wait , +.Fn wait3 , +and +.Fn wait4 +functions, the single .Fa wpid argument specifies the set of child processes for which to wait. +.Bl -bullet -offset indent +.It If .Fa wpid is -1, the call waits for any child process. +.It If .Fa wpid is 0, the call waits for any child process in the process group of the caller. +.It If .Fa wpid is greater than zero, the call waits for the process with process id .Fa wpid . +.It If .Fa wpid is less than -1, the call waits for any process whose process group id equals the absolute value of .Fa wpid . +.El .Pp The .Fa status @@ -116,41 +267,102 @@ argument is defined below. The .Fa options argument contains the bitwise OR of any of the following options. -The -.Dv WCONTINUED -option indicates that children of the current process that +.Bl -tag -width Ds +.It Dv WCONTINUED +indicates that children of the current process that have continued from a job control stop, by receiving a .Dv SIGCONT signal, should also have their status reported. -The -.Dv WNOHANG -option -is used to indicate that the call should not block if -there are no processes that wish to report status. -If the -.Dv WUNTRACED -option is set, -children of the current process that are stopped +.It Dv WNOHANG +is used to indicate that the call should not block when +there are no processes wishing to report status. +.It Dv WUNTRACED +indicates that children of the current process which are stopped due to a .Dv SIGTTIN , SIGTTOU , SIGTSTP , or .Dv SIGSTOP -signal also have their status reported. -The -.Dv WSTOPPED -option is an alias for +signal shall have their status reported. +.It Dv WSTOPPED +is an alias for .Dv WUNTRACED . -The -.Dv WNOWAIT -option keeps the process whose status is returned in a waitable state. +.It Dv WTRAPPED +allows waiting for processes which have trapped or reached a breakpoint. +.It Dv WEXITED +indicates that the caller is wants to receive status reports from +terminated processes. +This flag is implicitly set for the functions +.Fn wait , +.Fn waitpid , +.Fn wait3 , +and +.Fn wait4 . +.br +For the +.Fn waitid +and +.Fn wait6 +functions, the flag has to be explicitly included in the +.Fa options , +if status reports from terminated processes are expected. +.It Dv WNOWAIT +keeps the process whose status is returned in a waitable state. The process may be waited for again after this call completes. +.El +.sp +For the +.Fn waitid +and +.Fn wait6 +functions, at least one of the options +.Dv WEXITED , +.Dv WUNTRACED , +.Dv WSTOPPED , +.Dv WTRAPPED , +or +.Dv WCONTINUED +must be specified. +Otherwise there will be no events for the call to report. +To avoid hanging indefinitely in such a case these functions +return -1 with +.Dv errno +set to +.Dv EINVAL . .Pp If .Fa rusage -is non-zero, a summary of the resources used by the terminated -process and all its -children is returned (this information is currently not available -for stopped or continued processes). +is non-NULL, a summary of the resources used by the terminated +process and all its children is returned. +.Pp +If +.Fa wrusage +argument is non-NULL, a resource usage statistics +from both its own child process as well as from its grand children +is returned. +.Pp +If +.Fa infop +is non-NULL, it must point to a +.Dv siginfo_t +structure which is filled on return such that the +.Dv si_signo +field is always +.Dv SIGCHLD +and the field +.Dv si_pid +if be non-zero, if there is a status change to report. +If there are no status changes to report and WNOHANG is applied, +both of these fields are returned zero. +When using the +.Fn waitid +function with the +.Dv WNOHANG +option set, checking these fields is the only way to know whether +there were any status changes to report, because the return value +from +.Fn waitid +is be zero as it is for any successful return from +.Fn waitid . .Pp When the .Dv WNOHANG @@ -175,6 +387,20 @@ call is the same as with a .Fa wpid value of -1. +The +.Fn wait6 +call, with the bits +.Dv WEXITED +and +.Dv WTRAPPED +set in the +.Fa options +and with +.Fa infop +set to +.Dv NULL , +is similar to +.Fn wait4 . .Pp The following macros may be used to test the manner of exit of the process. One of the first four macros will evaluate to a non-zero (true) value: @@ -284,6 +510,7 @@ is returned and is set to indicate the error. .Pp If +.Fn wait6 , .Fn wait4 , .Fn wait3 , or @@ -306,6 +533,18 @@ a value of -1 is returned and .Va errno is set to indicate the error. +.Pp +If +.Fn waitid +returns because one or more processes have a state change to report, +0 is returned. +To indicate an error, -1 will be returned and +.Dv errno +set to an appropriate value. +If +.Dv WNOHANG +was used, 0 can be returned indicating no error, but no processes +may have changed state either, if si_signo and/or si_pid are zero. .Sh ERRORS The .Fn wait @@ -335,6 +574,14 @@ The call was interrupted by a caught sig or the signal did not have the .Dv SA_RESTART flag set. +.It Bq Er EINVAL +An invalid value was specified for +.Fa options , +or +.Fa idtype +and +.Fa id +do not specify a valid set of processes. .El .Sh SEE ALSO .Xr _exit 2 , @@ -344,11 +591,13 @@ flag set. .Xr siginfo 3 .Sh STANDARDS The -.Fn wait +.Fn wait , +.Fn waitpid , and -.Fn waitpid +.Fn waitid functions are defined by POSIX; -.Fn wait4 +.Fn wait6 , +.Fn wait4 , and .Fn wait3 are not specified by POSIX.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201212130627.qBD6RxvA063091>