From owner-svn-src-all@FreeBSD.ORG Wed Dec 17 01:32:28 2014 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 76EE5DA1; Wed, 17 Dec 2014 01:32:28 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 57CC6FE4; Wed, 17 Dec 2014 01:32:28 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.9/8.14.9) with ESMTP id sBH1WS9v041488; Wed, 17 Dec 2014 01:32:28 GMT (envelope-from mckusick@FreeBSD.org) Received: (from mckusick@localhost) by svn.freebsd.org (8.14.9/8.14.9/Submit) id sBH1WSMI041487; Wed, 17 Dec 2014 01:32:28 GMT (envelope-from mckusick@FreeBSD.org) Message-Id: <201412170132.sBH1WSMI041487@svn.freebsd.org> X-Authentication-Warning: svn.freebsd.org: mckusick set sender to mckusick@FreeBSD.org using -f From: Kirk McKusick Date: Wed, 17 Dec 2014 01:32:28 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r275846 - head/lib/libc/sys X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 17 Dec 2014 01:32:28 -0000 Author: mckusick Date: Wed Dec 17 01:32:27 2014 New Revision: 275846 URL: https://svnweb.freebsd.org/changeset/base/275846 Log: Add some additional clarification and fix a few gammer nits. Reviewed by: kib MFC after: 3 weeks Modified: head/lib/libc/sys/procctl.2 Modified: head/lib/libc/sys/procctl.2 ============================================================================== --- head/lib/libc/sys/procctl.2 Wed Dec 17 00:22:41 2014 (r275845) +++ head/lib/libc/sys/procctl.2 Wed Dec 17 01:32:27 2014 (r275846) @@ -101,25 +101,25 @@ Future child processes will also mark al .El .It Dv PROC_REAP_ACQUIRE Acquires the reaper status for the current process. -The status means that orphaned children by the reaper descendants, -forked after the acquisition of the status, are reparented to the +The status means that children orphaned by the reaper's descendants +that were forked after the acquisition of the status are reparented to the reaper. After the system initialization, .Xr init 8 is the default reaper. .Pp .It Dv PROC_REAP_RELEASE -Releases the reaper state fpr the current process. +Releases the reaper state for the current process. The reaper of the current process becomes the new reaper of the -current process descendants. +current process's descendants. .It Dv PROC_REAP_STATUS Provides the information about the reaper of the specified process, -or the process itself, in case it is a reaper. +or the process itself when it is a reaper. The .Fa data -argument must point to the -.Vt "struct procctl_reaper_status" , -which if filled by the syscall on successfull return. +argument must point to a +.Vt procctl_reaper_status +structure which is filled in by the syscall on successful return. .Bd -literal struct procctl_reaper_status { u_int rs_flags; @@ -134,57 +134,62 @@ The may have the following flags returned: .Bl -tag -width "Dv REAPER_STATUS_REALINIT" .It Dv REAPER_STATUS_OWNED -The specified process has acquired the reaper status and did not +The specified process has acquired the reaper status and has not released it. -When the flag is returned, the -.Fa id -pid identifies reaper, otherwise the +When the flag is returned, the specified process +.Fa id , +pid, identifies the reaper, otherwise the .Fa rs_reaper -field of the structure is the pid of the reaper for passed process id. +field of the structure is set to the pid of the reaper +for the specified process id. .It Dv REAPER_STATUS_REALINIT The specified process is the root of the reaper tree, i.e. -.Xr init 8. +.Xr init 8 . .El The .Fa rs_children -returns the number of the children of the reaper. +field returns the number of children of the reaper. The .Fa rs_descendants -returns the total number of descendants of the reaper, -not counting descendants of the reapers in the subtree. +field returns the total number of descendants of the reaper(s), +not counting descendants of the reaper in the subtree. The .Fa rs_reaper -returns the reaper pid. +field returns the reaper pid. The .Fa rs_pid -returns pid of some reaper child if there is any descendant. +returns the pid of one reaper child if there are any descendants. .It Dv PROC_REAP_GETPIDS Queries the list of descendants of the reaper of the specified process. -The request takes the pointer to -.Vt "struct procctl_reaper_pids" -as -.Fa data . +The request takes a pointer to a +.Vt procctl_reaper_pids +structure in the +.Fa data +parameter. .Bd -literal struct procctl_reaper_pids { u_int rp_count; struct procctl_reaper_pidinfo *rp_pids; }; .Ed -On call, the +When called, the .Fa rp_pids -must point to the array of +field must point to an array of .Vt procctl_reaper_pidinfo -structures, to be filled on return, +structures, to be filled in on return, and the .Fa rp_count -must specify the size of the array, -no more than rp_count elements is filled by kernel. +field must specify the size of the array, +into which no more than +.Fa rp_count +elements will be filled in by the kernel. .Pp The .Vt "struct procctl_reaper_pidinfo" -structure provides some information about one reaper' descendant. -Note that for the descendant which is not child, it is the subject -of usual race with process exiting and pid reuse. +structure provides some information about one of the reaper's descendants. +Note that for a descendant that is not a child, it may be incorrectly +identified because of a race in which the original child process exited +and the exited process's pid was reused for an unrelated process. .Bd -literal struct procctl_reaper_pidinfo { pid_t pi_pid; @@ -194,33 +199,35 @@ struct procctl_reaper_pidinfo { .Ed The .Fa pi_pid -is the process id of the descendant. +field is the process id of the descendant. The .Fa pi_subtree -provides the pid of the child of the reaper, which is (grand-)parent +field provides the pid of the child of the reaper, which is the (grand-)parent of the process. The .Fa pi_flags -returns the following flags, further describing the descendant: +field returns the following flags, further describing the descendant: .Bl -tag -width "Dv REAPER_PIDINFO_VALID" .It Dv REAPER_PIDINFO_VALID -Set for the +Set to indicate that the .Vt procctl_reaper_pidinfo -structure, which was filled by kernel. +structure was filled in by the kernel. Zero-filling the .Fa rp_pids -array and testing the flag allows the caller to detect the end -of returned array. +array and testing the +.Dv REAPER_PIDINFO_VALID +flag allows the caller to detect the end +of the returned array. .It Dv REAPER_PIDINFO_CHILD The .Fa pi_pid -is the direct child of the reaper. +field identifies the direct child of the reaper. .El .It Dv PROC_REAP_KILL -Request to deliver a signal to some subset of descendants of the reaper. +Request to deliver a signal to some subset of the descendants of the reaper. The .Fa data -must point to +parameter must point to a .Vt procctl_reaper_kill structure, which is used both for parameters and status return. .Bd -literal @@ -234,39 +241,40 @@ struct procctl_reaper_kill { .Ed The .Fa rk_sig -specifies the signal to be delivered. +field specifies the signal to be delivered. Zero is not a valid signal number, unlike .Xr kill 2 . The .Fa rk_flags -further directs the operation. +field further directs the operation. It is or-ed from the following flags: .Bl -tag -width "Dv REAPER_KILL_CHILDREN" .It Dv REAPER_KILL_CHILDREN Deliver the specified signal only to direct children of the reaper. .It Dv REAPER_KILL_SUBTREE -Deliver the specified signal only to descendants which were forked by -the direct child with pid specified in -.Fa rk_subtree . +Deliver the specified signal only to descendants that were forked by +the direct child with pid specified in the +.Fa rk_subtree +field. .El -If no +If neither the .Dv REAPER_KILL_CHILDREN -and +nor the .Dv REAPER_KILL_SUBTREE flags are specified, all current descendants of the reaper are signalled. .Pp -If signal was delivered to any process, the return value from the request +If a signal was delivered to any process, the return value from the request is zero. -In this case, +In this case, the .Fa rk_killed -field is filled with the count of processes signalled. +field identifies the number of processes signalled. The .Fa rk_fpid field is set to the pid of the first process for which signal delivery failed, e.g. due to the permission problems. If no such process exist, the .Fa rk_fpid -is set to -1. +field is set to -1. .El .Sh RETURN VALUES If an error occurs, a value of -1 is returned and @@ -281,7 +289,7 @@ will fail if: .It Bq Er EFAULT The .Fa arg -points outside the process's allocated address space. +parameter points outside the process's allocated address space. .It Bq Er EINVAL The .Fa cmd @@ -317,11 +325,11 @@ or .Dv PROC_REAP_RELEASE requests. .It Bq Er EINVAL -Invalid or undefined flags were passed to +Invalid or undefined flags were passed to a .Dv PROC_REAP_KILL request. .It Bq Er EINVAL -Invalid or zero signal number was requested for +An invalid or zero signal number was requested for a .Dv PROC_REAP_KILL request. .It Bq Er EINVAL @@ -333,8 +341,8 @@ process. .It Bq Er EBUSY The .Dv PROC_REAP_ACQUIRE -request was issued by the process which already acquired reaper status -and did not released it. +request was issued by a process that had already acquired reaper status +and has not yet released it. .El .Sh SEE ALSO .Xr kill 2 , @@ -346,6 +354,6 @@ The .Fn procctl function appeared in .Fx 10.0 . -Reaper facility was created based on the similar feature of Linux and +The reaper facility is based on a similar feature of Linux and DragonflyBSD, and first appeared in .Fx 10.2 .