From nobody@FreeBSD.org  Thu Aug  9 09:12:40 2001
Return-Path: <nobody@FreeBSD.org>
Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21])
	by hub.freebsd.org (Postfix) with ESMTP id 3F64337B401
	for <freebsd-gnats-submit@FreeBSD.org>; Thu,  9 Aug 2001 09:12:40 -0700 (PDT)
	(envelope-from nobody@FreeBSD.org)
Received: (from nobody@localhost)
	by freefall.freebsd.org (8.11.4/8.11.4) id f79GCea54375;
	Thu, 9 Aug 2001 09:12:40 -0700 (PDT)
	(envelope-from nobody)
Message-Id: <200108091612.f79GCea54375@freefall.freebsd.org>
Date: Thu, 9 Aug 2001 09:12:40 -0700 (PDT)
From: Evan Sarmiento <kaworu@sektor7.ath.cx>
To: freebsd-gnats-submit@FreeBSD.org
Subject: [PATCH] No man page for pgrp kernel functions
X-Send-Pr-Version: www-1.0

>Number:         29571
>Category:       docs
>Synopsis:       [PATCH] No man page for pgrp kernel functions
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Aug 09 09:20:01 PDT 2001
>Closed-Date:    Tue Apr 01 08:11:19 PST 2003
>Last-Modified:  Tue Apr 01 08:11:19 PST 2003
>Originator:     Evan Sarmiento
>Release:        5.0-RELEASE
>Organization:
>Environment:
FreeBSD armitage.sekt7.org 5.0-CURRENT FreeBSD 5.0-CURRENT #2: Sat Aug  4 15:43:02 EDT 2001     root@armitage.sekt7.org:/usr/src/sys/i386/compile/INSPIRON  i386

>Description:
No manpage for the pgrp() functions loacted in /usr/src/sys/kern/kern_proc.c. This manpages references three functions,
enterpgrp, leavepgrp, and pgdelete.
>How-To-Repeat:

>Fix:
.\" Copyright (c) 2001 Evan Sarmiento.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"
.Dd August 8, 2001
.Os
.Dt PGFIND 9
.Sh NAME
.Nm enterpgrp, leavepgrp, pgdelete 
.Nd functions for manipulating process groups 
.Sh SYNOPSIS
.In sys/proc.h
.Ft "int"
.Fn enterpgrp "struct proc *p, pid_t pgid, int mksess"
.Ft "int"
.Fn leavepgrp "struct proc *p"
.Ft "static void"
.Fn pgdelete  "struct pgrp *pgrp"
.Sh DESCRIPTION
.Fn enterpgrp 
takes three arguments: 
.Fa p
.Fa pgid
and
.Fa mksess.
.Fa p
represents a pointer to a 
.Fa proc
structure which is going to enter the process group refrenced by
.Fa pgid.
.Fa mksses
is an option, that when toggled, makes
.Fa p
the leader of a new session. 
.Pp
If 
.Fa pgrp
is
.Fa NULL
the process specified by
.Fa p
becomes the leader of the process group.
.Pp
.Fn leavepgrp
only takes one argument, a pointer to a
.Fa proc
structure designated by
.Fa p.
.Fa pgrp
removes the proc structure referenced by p from its proces group.
.Pp
.Fn pgdelete
requires one argument, 
.Fa pgrp,
which is a pointer to a pgrp structure. 
.Fn pgdelete
deletes the process group
whose number is referenced by 
.Fa pgrp. 
.Sh RETURN VALUES
.Fn enterpgrp
returns a 
.Fa ESRCH
if the process specified in the argument could not be found, otherwise it returns 0 on success.
.Pp
.Fn leavepgrp
only returns 0.
.Pp
.Fn pgdelete
does not return anything, as it is a void function.
.Sh AUTHORS
This man page was written by
.An Evan Sarmiento Aq kaworu@sektor7.ath.cx .

>Release-Note:
>Audit-Trail:

From: Dima Dorfman <dima@unixfreak.org>
To: Evan Sarmiento <kaworu@sektor7.ath.cx>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/29571: [PATCH] No man page for pgrp kernel functions 
Date: Mon, 03 Sep 2001 09:15:51 -0700

 Evan Sarmiento <kaworu@sektor7.ath.cx> wrote:
 > >Description:
 > No manpage for the pgrp() functions loacted in /usr/src/sys/kern/kern_proc.c.
 >  This manpages references three functions,
 > enterpgrp, leavepgrp, and pgdelete.
 > >How-To-Repeat:
 > 
 > >Fix:
 > .\" Copyright (c) 2001 Evan Sarmiento.
 > .\" All rights reserved.
 > .\"
 > .\" Redistribution and use in source and binary forms, with or without
 > .\" modification, are permitted provided that the following conditions
 > .\" are met:
 > .\" 1. Redistributions of source code must retain the above copyright
 > .\"    notice, this list of conditions and the following disclaimer.
 > .\" 2. Redistributions in binary form must reproduce the above copyright
 > .\"    notice, this list of conditions and the following disclaimer in the
 > .\"    documentation and/or other materials provided with the distribution.
 > .\"
 > .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 > .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 > .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 > .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 > .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 > .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 > .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 > .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 > .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 > .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 > .\" SUCH DAMAGE.
 > .\"
 > .\"
 > .Dd August 8, 2001
 > .Os
 > .Dt PGFIND 9
 
 This is not pgfind(9).
 
 > .Sh NAME
 > .Nm enterpgrp, leavepgrp, pgdelete 
 
 You need whitespace in front of punctuation, as so:
 
 	.Nm enterpgrp , leavepgrp , pgdelete
 
 And you don't need whitespace at the end of the line.
 
 > .Nd functions for manipulating process groups 
 > .Sh SYNOPSIS
 > .In sys/proc.h
 > .Ft "int"
 > .Fn enterpgrp "struct proc *p, pid_t pgid, int mksess"
 
 The parameters should be separated.  E.g.:
 
 .Fn enterpgrp "struct proc *p" "pid_t pgid" "int mksess"
 
 > .Ft "int"
 > .Fn leavepgrp "struct proc *p"
 > .Ft "static void"
 > .Fn pgdelete  "struct pgrp *pgrp"
 
 pgdelete is not meant to be used by anything outside of kern_proc
 (which is why it's "static"), so a man page for it is rather useless.
 Better improve the comments if you want to document it.
 
 > .Sh DESCRIPTION
 > .Fn enterpgrp 
 > takes three arguments: 
 > .Fa p
 > .Fa pgid
 > and
 > .Fa mksess.
 
 Please use punctuation (commas), and don't forget the space before
 them if they're in a macro.
 
 	.Fa p ,
 	.Fa pgid ,
 	and
 	.Fa mksess .
 
 
 > .Fa p
 > represents a pointer to a 
 > .Fa proc
 
 .Vt proc
 
 > structure which is going to enter the process group refrenced by
 > .Fa pgid.
 
 Space before period.
 
 > .Fa mksses
 > is an option, that when toggled, makes
 > .Fa p
 > the leader of a new session. 
 > .Pp
 > If 
 > .Fa pgrp
 > is
 > .Fa NULL
 
 .Dv NULL ,
 
 > the process specified by
 > .Fa p
 > becomes the leader of the process group.
 > .Pp
 > .Fn leavepgrp
 > only takes one argument, a pointer to a
 > .Fa proc
 > structure designated by
 > .Fa p.
 
 Space before period.
 
 > .Fa pgrp
 > removes the proc structure referenced by p from its proces group.
 
 ... referenced by
 .Fa p
 from its ...
 
 > .Pp
 > .Fn pgdelete
 > requires one argument, 
 > .Fa pgrp,
 
 Space before the comma.
 
 > which is a pointer to a pgrp structure. 
 
 ... a
 .Vt pgrp
 structure ...
 
 > .Fn pgdelete
 > deletes the process group
 > whose number is referenced by 
 > .Fa pgrp. 
 
 pgdelete is not an interface.
 
 > .Sh RETURN VALUES
 > .Fn enterpgrp
 > returns a 
 > .Fa ESRCH
 
 .Er ESRCH
 
 
 I've not verified the technical accuracy of this stuff, and there are
 also some more lines with whitespace at the end.  It's good work, but
 it could use improvement :-).
 
 Thanksk.
State-Changed-From-To: open->feedback 
State-Changed-By: dd 
State-Changed-When: Sun Oct 14 16:38:20 PDT 2001 
State-Changed-Why:  
Awaiting submitter feedback re: my suggestions. 

http://www.FreeBSD.org/cgi/query-pr.cgi?pr=29571 
State-Changed-From-To: feedback->open 
State-Changed-By: keramida 
State-Changed-When: Sun Jul 14 22:40:24 PDT 2002 
State-Changed-Why:  
Revert this to `open' to avoid having it closed 
during a feedback timeout sweep. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=29571 
Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Tue Feb 25 07:50:55 PST 2003 
Responsible-Changed-Why:  
I'll take this. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=29571 
State-Changed-From-To: open->closed 
State-Changed-By: trhodes 
State-Changed-When: Tue Apr 1 08:10:51 PST 2003 
State-Changed-Why:  
Someone has already committed this to my suprise.  Thanks for the 
submission! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=29571 
>Unformatted:
