From nobody@FreeBSD.org  Tue Nov 12 17:14:24 2013
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1])
	(using TLSv1 with cipher ADH-AES256-SHA (256/256 bits))
	(No client certificate requested)
	by hub.freebsd.org (Postfix) with ESMTPS id F178D97C
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 12 Nov 2013 17:14:24 +0000 (UTC)
Received: from oldred.freebsd.org (oldred.freebsd.org [8.8.178.121])
	(using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
	(No client certificate requested)
	by mx1.freebsd.org (Postfix) with ESMTPS id E185B2DC3
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 12 Nov 2013 17:14:24 +0000 (UTC)
Received: from oldred.freebsd.org ([127.0.1.6])
	by oldred.freebsd.org (8.14.5/8.14.7) with ESMTP id rACHEOfH030166
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 12 Nov 2013 17:14:24 GMT
	(envelope-from nobody@oldred.freebsd.org)
Received: (from nobody@localhost)
	by oldred.freebsd.org (8.14.5/8.14.5/Submit) id rACHEOk9030162;
	Tue, 12 Nov 2013 17:14:24 GMT
	(envelope-from nobody)
Message-Id: <201311121714.rACHEOk9030162@oldred.freebsd.org>
Date: Tue, 12 Nov 2013 17:14:24 GMT
From: Michael Galassi <michaelgalassi@gmail.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: wpid argument in wait(2) manpage is mischarachterized.
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         183904
>Category:       docs
>Synopsis:       wpid argument in wait(2) manpage is mischarachterized.
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    jhb
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Nov 12 17:20:00 UTC 2013
>Closed-Date:    Tue Dec 03 21:00:37 UTC 2013
>Last-Modified:  Tue Dec  3 21:10:00 UTC 2013
>Originator:     Michael Galassi
>Release:        10.0-BETA3
>Organization:
me
>Environment:
FreeBSD penguin.arrs.arrisi.com 10.0-BETA3 FreeBSD 10.0-BETA3 #0 r258002: Mon Nov 11 12:17:07 PST 2013     root@penguin.arrs.arrisi.com:/usr/obj/usr/src/sys/PENGUIN  amd64

>Description:
The man page for wait includes the sentence:

For wait(), wait3(), and wait4() functions, the single wpid argument specifies the set of child processes for which to wait.

wait() and wait3() however do not take a wpid argument.
>How-To-Repeat:
man 2 wait
>Fix:
I am reasonably certain that this sentence was meant to read:
was meant to refer to waitpid() and wait4() only.

For waitpid() and wait4() functions, the wpid argument specifies the set of child processes for which to wait.

>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->jhb 
Responsible-Changed-By: jhb 
Responsible-Changed-When: Tue Nov 12 18:24:49 UTC 2013 
Responsible-Changed-Why:  
I'll take this. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=183904 

From: John Baldwin <jhb@freebsd.org>
To: freebsd-doc@freebsd.org
Cc: Michael Galassi <michaelgalassi@gmail.com>,
 freebsd-gnats-submit@freebsd.org
Subject: Re: docs/183904: wpid argument in wait(2) manpage is mischarachterized.
Date: Tue, 12 Nov 2013 13:24:49 -0500

 On Tuesday, November 12, 2013 12:14:24 pm Michael Galassi wrote:
 > 
 > >Number:         183904
 > >Category:       docs
 > >Synopsis:       wpid argument in wait(2) manpage is mischarachterized.
 > >Confidential:   no
 > >Severity:       non-critical
 > >Priority:       low
 > >Responsible:    freebsd-doc
 > >State:          open
 > >Quarter:        
 > >Keywords:       
 > >Date-Required:
 > >Class:          doc-bug
 > >Submitter-Id:   current-users
 > >Arrival-Date:   Tue Nov 12 17:20:00 UTC 2013
 > >Closed-Date:
 > >Last-Modified:
 > >Originator:     Michael Galassi
 > >Release:        10.0-BETA3
 > >Organization:
 > me
 > >Environment:
 > FreeBSD penguin.arrs.arrisi.com 10.0-BETA3 FreeBSD 10.0-BETA3 #0 r258002: 
 Mon Nov 11 12:17:07 PST 2013     
 root@penguin.arrs.arrisi.com:/usr/obj/usr/src/sys/PENGUIN  amd64
 > 
 > >Description:
 > The man page for wait includes the sentence:
 > 
 > For wait(), wait3(), and wait4() functions, the single wpid argument 
 specifies the set of child processes for which to wait.
 > 
 > wait() and wait3() however do not take a wpid argument.
 > >How-To-Repeat:
 > man 2 wait
 > >Fix:
 > I am reasonably certain that this sentence was meant to read:
 > was meant to refer to waitpid() and wait4() only.
 > 
 > For waitpid() and wait4() functions, the wpid argument specifies the set of 
 child processes for which to wait.
 
 I have a large update pending to wait(2), so I will take this.
 
 -- 
 John Baldwin
State-Changed-From-To: open->closed 
State-Changed-By: jhb 
State-Changed-When: Tue Dec 3 21:00:21 UTC 2013 
State-Changed-Why:  
Committed to HEAD as part of a larger change.  Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=183904 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/183904: commit references a PR
Date: Tue,  3 Dec 2013 21:00:21 +0000 (UTC)

 Author: jhb
 Date: Tue Dec  3 21:00:13 2013
 New Revision: 258891
 URL: http://svnweb.freebsd.org/changeset/base/258891
 
 Log:
   Various updates and tweaks to the wait(2) manpage.
   
   PR:		docs/183904
   Submitted by:	Michael Galassi <michaelgalassi@gmail.com>
   Reviewed by:	kib, wblock (earlier version)
 
 Modified:
   head/lib/libc/sys/wait.2
 
 Modified: head/lib/libc/sys/wait.2
 ==============================================================================
 --- head/lib/libc/sys/wait.2	Tue Dec  3 20:55:37 2013	(r258890)
 +++ head/lib/libc/sys/wait.2	Tue Dec  3 21:00:13 2013	(r258891)
 @@ -28,7 +28,7 @@
  .\"     @(#)wait.2	8.2 (Berkeley) 4/19/94
  .\" $FreeBSD$
  .\"
 -.Dd September 7, 2013
 +.Dd December 3, 2013
  .Dt WAIT 2
  .Os
  .Sh NAME
 @@ -62,63 +62,76 @@
  .Sh DESCRIPTION
  The
  .Fn wait
 -function suspends execution of its calling process until
 +function suspends execution of its calling thread until
  .Fa status
 -information is available for a terminated child process,
 +information is available for a child process
  or a signal is received.
  On return from a successful
  .Fn wait
  call,
  the
  .Fa status
 -area contains termination information about the process that exited
 +area contains information about the process that reported a status change
  as defined below.
 -The
 -.Fn wait
 -call is the same as
 -.Fn wait4
 -with a
 -.Fa wpid
 -value of -1,
 -with an
 -.Fa options
 -value of zero,
 -and a
 -.Fa rusage
 -value of zero.
  .Pp
  The
  .Fn wait4
 -system call provides a more general interface for programs
 -that need to wait for certain child processes,
 +and
 +.Fn wait6
 +system calls provide a more general interface for programs
 +that need to wait for specific child processes,
  that need resource utilization statistics accumulated by child processes,
  or that require options.
 +The other wait functions are implemented using either
 +.Fn wait4
 +or
 +.Fn wait6 .
  .Pp
 -The broadest interface of all functions in this family is
 +The
  .Fn wait6
 -which is otherwise very much like
 +function is the most general function in this family and its distinct
 +features are:
 +.Pp
 +All of the desired process statuses to be waited on must be explicitly
 +specified in
 +.Fa options .
 +The
 +.Fn wait ,
 +.Fn waitpid ,
 +.Fn wait3 ,
 +and
  .Fn wait4
 -but with a few very important distinctions.
 -To wait for exited processes, the option flag
 +functions all implicitly wait for exited and trapped processes,
 +but the
 +.Fn waitid 
 +and
 +.Fn wait6
 +functions require the corresponding
  .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
 +and
 +.Dv WTRAPPED
 +flags to be explicitly specified.
 +This allows waiting for processes which have experienced other
 +status changes without having to also handle the exit status from
 +terminated processes.
 +.Pp
 +The
 +.Fn wait6
 +function accepts a
 +.Fa wrusage
 +argument which points to a structure defined as:
  .Bd -literal
  struct __wrusage {
  	struct rusage   wru_self;
  	struct rusage   wru_children;
  };
  .Ed
 -can be passed.
 +.Pp
  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 .
 +.Pp
  The last argument
  .Fa infop
  must be either
 @@ -126,11 +139,13 @@ must be either
  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
 +If
 +.Pf non- Dv NULL ,
 +the structure is filled with the same data as for a
 +.Dv SIGCHLD
 +signal delivered when the process changed state.
 +.Pp
 +The set of child processes to be queried is specified by the arguments
  .Fa idtype
  and
  .Fa id .
 @@ -138,8 +153,8 @@ The separate
  .Fa idtype
  and
  .Fa id
 -arguments allows to support many other types of
 -IDs  as well in addition to PID and PGID.
 +arguments support many other types of
 +identifers in addition to process IDs and process group IDs.
  .Bl -bullet -offset indent
  .It
  If
 @@ -188,50 +203,33 @@ and
  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
 +Non-standard identifier types supported by this 
  implementation of
  .Fn waitid
  and
 -.Fn wait6 ,
 +.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 .
 +.Bl -tag -width P_JAILID
 +.It Dv P_UID
 +Wait for processes whose effective user ID is equal to
 +.Dv (uid_t) Fa id .
 +.It Dv P_GID
 +Wait for processes whose effective group ID is equal to
 +.Dv (gid_t) Fa id .
 +.It Dv P_SID
 +Wait for processes whose session ID is equal to
 +.Fa id .
 +.\" This is just how sessions work, not sure this needs to be documented here
 +If the child process started its own session,
 +its session ID will be the same as its process ID.
 +Otherwise the session ID of a child process will match the caller's session ID.
 +.It Dv P_JAILID
 +Waits for processes within a jail whose jail identifier is equal to
 +.Fa id .
  .El
  .Pp
 -For
 -.Fn wait ,
 -.Fn wait3 ,
 +For the
 +.Fn waitpid
  and
  .Fn wait4
  functions, the single
 @@ -250,12 +248,12 @@ the call waits for any child process in 
  .It
  If
  .Fa wpid
 -is greater than zero, the call waits for the process with process id
 +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
 +is less than -1, the call waits for any process whose process group ID
  equals the absolute value of
  .Fa wpid .
  .El
 @@ -267,30 +265,44 @@ argument is defined below.
  The
  .Fa options
  argument contains the bitwise OR of any of the following options.
 -.Bl -tag -width Ds
 +.Bl -tag -width WCONTINUED
  .It Dv WCONTINUED
 -indicates that children of the current process that
 -have continued from a job control stop, by receiving a
 +Report the status of selected processes that
 +have continued from a job control stop by receiving a
  .Dv SIGCONT
 -signal, should also have their status reported.
 +signal.
  .It Dv WNOHANG
 -is used to indicate that the call should not block when
 +Do 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
 +Report the status of selected processes which are stopped due to a
  .Dv SIGTTIN , SIGTTOU , SIGTSTP ,
  or
  .Dv SIGSTOP
 -signal shall have their status reported.
 +signal.
  .It Dv WSTOPPED
 -is an alias for
 +An alias for
  .Dv WUNTRACED .
  .It Dv WTRAPPED
 -allows waiting for processes which have trapped or reached a breakpoint.
 +Report the status of selected processes which are being traced via
 +.Xr ptrace 2
 +and have trapped or reached a breakpoint.
 +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
 +.Fa options
 +if status reports from trapped processes are expected.
  .It Dv WEXITED
 -indicates that the caller is wants to receive status reports from
 -terminated processes.
 +Report the status of selected processes which have terminated.
  This flag is implicitly set for the functions
  .Fn wait ,
  .Fn waitpid ,
 @@ -302,11 +314,11 @@ For the
  .Fn waitid
  and
  .Fn wait6
 -functions, the flag has to be explicitly included in the
 -.Fa options ,
 +functions, the flag has to be explicitly included in
 +.Fa options
  if status reports from terminated processes are expected.
  .It Dv WNOWAIT
 -keeps the process whose status is returned in a waitable state.
 +Keep the process whose status is returned in a waitable state.
  The process may be waited for again after this call completes.
  .El
  .sp
 @@ -336,50 +348,68 @@ 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.
 +is non-NULL, separate summaries are returned for the resources used
 +by the terminated process and the resources used by all its children.
  .Pp
  If
  .Fa infop
 -is non-NULL, it must point to a
 +is non-NULL, a
  .Dv siginfo_t
 -structure which is filled on return such that the
 -.Dv si_signo
 -field is always
 +structure is returned with the
 +.Fa si_signo
 +field set to
  .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
 +and the
 +.Fa si_pid
 +field set to the process ID of the process reporting status.
 +.Pp
 +When 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
 +option is specified and no processes
 +wish to report status,
  .Fn waitid
 -is be zero as it is for any successful return from
 -.Fn waitid .
 +sets the
 +.Fa si_signo
 +and
 +.Fa si_pid
 +fields in
 +.Fa infop
 +to zero.
 +Checking these fields is the only way to know if a status change was reported.
  .Pp
  When the
  .Dv WNOHANG
  option is specified and no processes
  wish to report status,
  .Fn wait4
 -returns a
 +and
 +.Fn wait6
 +return a
  process id
  of 0.
  .Pp
  The
 +.Fn wait
 +call is the same as
 +.Fn wait4
 +with a
 +.Fa wpid
 +value of -1,
 +with an
 +.Fa options
 +value of zero,
 +and a
 +.Fa rusage
 +value of
 +.Dv NULL .
 +The
  .Fn waitpid
  function is identical to
  .Fn wait4
  with an
  .Fa rusage
 -value of zero.
 +value of
 +.Dv NULL .
  The older
  .Fn wait3
  call is the same as
 @@ -388,29 +418,31 @@ with a
  .Fa wpid
  value of -1.
  The
 +.Fn wait4
 +function is identical to
  .Fn wait6
 -call, with the bits
 +with the flags
  .Dv WEXITED
  and
  .Dv WTRAPPED
 -set in the
 +set in
  .Fa options
 -and with
 +and
  .Fa infop
  set to
 -.Dv NULL ,
 -is similar to
 -.Fn wait4 .
 +.Dv NULL .
  .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:
 +The following macros may be used to test the current status of the process.
 +Exactly one of the following four macros will evaluate to a non-zero
 +.Pq true
 +value:
  .Bl -tag -width Ds
  .It Fn WIFCONTINUED status
  True if the process has not terminated, and
  has continued after a job control stop.
  This macro can be true only if the wait call specified the
  .Dv WCONTINUED
 -option).
 +option.
  .It Fn WIFEXITED status
  True if the process terminated normally by a call to
  .Xr _exit 2
 @@ -481,7 +513,7 @@ in
  The implementation queues one
  .Dv SIGCHLD
  signal for each child process whose
 -status has changed, if
 +status has changed; if
  .Fn wait
  returns because the status of a child process is available, the pending
  SIGCHLD signal associated with the process ID of the child process will
 @@ -492,7 +524,7 @@ signals remain pending.
  .Pp
  If
  .Dv SIGCHLD
 -is blocked,
 +is blocked and
  .Fn wait
  returns because the status of a child process is available, the pending
  .Dv SIGCHLD
 @@ -538,13 +570,23 @@ 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 an error is detected,
 +a value of -1
 +is returned and
 +.Va errno
 +is set to indicate the error.
  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.
 +is specified and there are
 +no stopped, continued or exited children,
 +0 is returned.
 +The
 +.Fa si_signo
 +and
 +.Fa si_pid
 +fields of
 +.Fa infop
 +must be checked against zero to determine if a process reported status.
  .Sh ERRORS
  The
  .Fn wait
 @@ -620,7 +662,7 @@ requires
  .Fn waitid
  to return the full 32 bits passed to
  .Xr _exit 2 ;
 -this implementation only returns 8 bits like in the other calls.
 +this implementation only returns 8 bits like the other calls.
  .Sh HISTORY
  The
  .Fn wait
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
>Unformatted:
