From nobody@FreeBSD.org  Thu Jul 12 18:03:49 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 30BEF37B401
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 12 Jul 2001 18:03:49 -0700 (PDT)
	(envelope-from nobody@FreeBSD.org)
Received: (from nobody@localhost)
	by freefall.freebsd.org (8.11.4/8.11.4) id f6D13nR54875;
	Thu, 12 Jul 2001 18:03:49 -0700 (PDT)
	(envelope-from nobody)
Message-Id: <200107130103.f6D13nR54875@freefall.freebsd.org>
Date: Thu, 12 Jul 2001 18:03:49 -0700 (PDT)
From: Evan Sarmiento <kaworu@sektor7.ath.cx>
To: freebsd-gnats-submit@FreeBSD.org
Subject: [patch] No man page for pfind()
X-Send-Pr-Version: www-1.0

>Number:         28929
>Category:       misc
>Synopsis:       [patch] No man page for pfind()
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    ru
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jul 12 18:10:00 PDT 2001
>Closed-Date:    Mon Jul 16 00:01:27 PDT 2001
>Last-Modified:  Mon Jul 16 00:04:13 PDT 2001
>Originator:     Evan Sarmiento
>Release:        4.3
>Organization:
>Environment:
FreeBSD teqnix.sekt7.org 4.3-RELEASE FreeBSD 4.3-RELEASE #17: Wed Jul 11 04:21:57 GMT 2001     root@teqnix.sekt7.org:/usr/home/kaworu/work/jailuser/current/src/sys/compile/KAWORU  i386

>Description:
I have created a manpage for pfind(). Manpage pasted below:
>How-To-Repeat:

>Fix:
.\" -*- nroff -*-
.\"
.\" Copyright (c) 1996 Doug Rabson
.\"
.\" All rights reserved.
.\"
.\" This program is free software.
.\"
.\" 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 DEVELOPERS ``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 DEVELOPERS 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 July 11, 2001
.Os
.Dt pfind 9
.Sh NAME
.Nm pfind
.Nd returns pointer to a proc structure in argument
.Sh SYNOPSIS
.Fd #include <sys/proc.h>
.Ft struct proc *
.Fn pfind "pid_t"
.Sh DESCRIPTION
.Pp
pfind takes a pid as its argument and returns a pointer to the proc structure wh
o's PID is the pid
specified in the argument
.Sh RETURN VALUES
pfind returns a pointer to a proc structure on success and a NULL on failure.
.Sh AUTHORS
This man page was written by
Evan Sarmiento.

>Release-Note:
>Audit-Trail:

From: David Malone <dwmalone@maths.tcd.ie>
To: Evan Sarmiento <kaworu@sektor7.ath.cx>
Cc: freebsd-gnats-submit@FreeBSD.org
Subject: Re: misc/28929: [patch] No man page for pfind()
Date: Fri, 13 Jul 2001 09:36:20 +0100

 On Thu, Jul 12, 2001 at 06:03:49PM -0700, Evan Sarmiento wrote:
 > I have created a manpage for pfind(). Manpage pasted below:
 
 Sounds useful. I've a few small comments.
 
 > >Fix:
 > .\" -*- nroff -*-
 > .\"
 > .\" Copyright (c) 1996 Doug Rabson
 
 I think you can assign the copyright of the manual page to yourself.
 In -current I don't think calling pfind requires any locking in
 -current 'cos it seems to do locking itself, but you might want to
 check that with John Baldwin <jhb@freebsd.org>. Also, you should
 probably ask Ruslan <ru@freebsd.org> to check the mdoc for you.
 
 It might also be useful to document zpfind in the same man page?
 
 	David.
Responsible-Changed-From-To: freebsd-bugs->freebsd-doc 
Responsible-Changed-By: roam 
Responsible-Changed-When: Fri Jul 13 02:11:48 PDT 2001 
Responsible-Changed-Why:  
I believe this to be a doc issue. 
The manpage does need some mdoc(7) corrections, like, for instance.. 

--- pfind.9.orig        Fri Jul 13 12:17:00 2001 
+++ pfind.9     Fri Jul 13 12:18:08 2001 
@@ -37,11 +37,12 @@ 
.Fn pfind "pid_t" 
.Sh DESCRIPTION 
.Pp 
-pfind takes a pid as its argument and returns a pointer to the proc structure w 
h 
-o's PID is the pid 
-specified in the argument 
+.Nm 
+takes a pid as its argument and returns a pointer to the proc structure with 
+the specified process ID. 
.Sh RETURN VALUES 
-pfind returns a pointer to a proc structure on success and a NULL on failure. 
+.Nm 
+returns a pointer to a proc structure on success and a null pointer on failure. 
.Sh AUTHORS 
This man page was written by 
-Evan Sarmiento. 
+.An Evan Sarmiento . 

Also, the comments in the audit trail about the actual content seem relevant. 

http://www.FreeBSD.org/cgi/query-pr.cgi?pr=28929 

From: Evan Sarmiento <kaworu@sektor7.ath.cx>
To: freebsd-gnats-submit@FreeBSD.org, dwmalone@maths.tcd.ie
Cc:  
Subject: Re: misc/28929: [patch] No man page for pfind()
Date: Fri, 13 Jul 2001 10:23:52 -0400 (EDT)

 Hello,
 
 I have updated the pfind and zpfind manpage, hopefully, they are all correct now.
 
 .\" -*- nroff -*-
 .\"
 .\" Copyright (c) 2001 Evan Sarmiento
 .\"
 .\" All rights reserved.
 .\"
 .\" This program is free software.
 .\"
 .\" 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 DEVELOPERS ``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 DEVELOPERS 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 July 11, 2001
 .Os
 .Dt pfind 9
 .Sh NAME
 .Nm pfind, zpfind
 .Nd returns pointer to a proc structure in argument
 .Sh SYNOPSIS
 .Fd #include <sys/proc.h>
 .Ft struct proc *
 .Fn pfind "pid_t"
 .Ft static struct proc *
 .Fn zpfind "pid_t"
 .Sh DESCRIPTION
 .Pp
 .Fn pfind
 takes a pid as its argument and returns a pointer to the proc structure whose PID is
 specified in the argument.
 .Pp
 .Nm
 takes a pid as its argument. If zpfind finds a process whose pid is equal to that of argument and is
 a zombie process, zpfind returns a pointer to that proc structure.
 .Pp
 Both zpfind and pfind lock the proc structure that is returned using
 .Fn PROC_LOCK "p"
 .Sh RETURN VALUES
 .Nm
 and
 .Nm zpfind
 both return a pointer to a locked proc structure on success and a NULL on failure.
 .Sh AUTHORS
 This man page was written by
 .An Evan Sarmiento .
 

From: Ruslan Ermilov <ru@FreeBSD.org>
To: Evan Sarmiento <kaworu@sektor7.ath.cx>
Cc: dmwmalone@maths.tcd.ie, bug-followup@FreeBSD.org
Subject: Re: misc/28929: [patch] No man page for pfind()
Date: Fri, 13 Jul 2001 17:46:57 +0300

 --lrZ03NoBR/3+SXJZ
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 
 On Fri, Jul 13, 2001 at 10:04:22AM -0400, Evan Sarmiento wrote:
 > 
 > Hello,
 > 
 > I have edited the manpage a bit. And I also looked at the current source a bit,
 > it does lock the proc structure. Here is my updated manpage.
 > 
 Here's the cleaned up version module one technical question.
 It is my understanding from reading the code that pfind()
 will only locate processes that are on the `allproc' list
 (i.e., either runnable or sleeping), but not if the process
 is on `zombproc' list.  Right?  The manpage is silent on this.
 
 Please also tell me your e-mail address (if desired) to be
 included into the manpage's AUTHORS section.
 
 
 Cheers,
 -- 
 Ruslan Ermilov		Oracle Developer/DBA,
 ru@sunbay.com		Sunbay Software AG,
 ru@FreeBSD.org		FreeBSD committer,
 +380.652.512.251	Simferopol, Ukraine
 
 http://www.FreeBSD.org	The Power To Serve
 http://www.oracle.com	Enabling The Information Age
 
 --lrZ03NoBR/3+SXJZ
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: attachment; filename="pfind.9"
 
 .\" 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 July 11, 2001
 .Os
 .Dt PFIND 9
 .Sh NAME
 .Nm pfind , zpfind
 .Nd locate a process by number
 .Sh SYNOPSIS
 .In sys/proc.h
 .Ft "struct proc *"
 .Fn pfind "pid_t pid"
 .Ft "struct proc *"
 .Fn zpfind "pid_t pid"
 .Sh DESCRIPTION
 .Fn pfind
 takes a
 .Fa pid
 as its argument and returns a pointer to the
 .Vt proc
 structure whose PID is specified in the argument.
 .Pp
 .Fn zpfind
 takes a
 .Fa pid
 as its argument.
 If
 .Fn zpfind
 finds a process whose PID is equal to that of argument
 and is a zombie process,
 .Fn zpfind
 returns a pointer to that
 .Vt proc
 structure.
 .Pp
 Both
 .Fn pfind
 and
 .Fn zpfind
 lock the
 .Vt proc
 structure that is returned using
 .Fn PROC_LOCK "p" .
 .Sh RETURN VALUES
 .Fn pfind
 and
 .Fn zpfind
 return a pointer to a
 .Vt proc
 structure on success and a
 .Dv NULL
 on failure.
 .Sh AUTHORS
 This man page was written by
 .An Evan Sarmiento .
 
 --lrZ03NoBR/3+SXJZ--

From: Evan Sarmiento <kaworu@sektor7.ath.cx>
To: freebsd-gnats-submit@freebsd.org, ru@freebsd.org
Cc:  
Subject: Re: misc/28929: [patch] No man page for pfind() 
Date: Fri, 13 Jul 2001 16:04:14 -0400 (EDT)

 Hello again,
 
 You're right about the allproc and zombproc thing. I've included them in the
 man page now. I've also included my email address at the bottom.
 
 Here is the diff.
 
 --- pfind       Thu Jul 12 04:00:58 2001
 +++ pfind.orig  Thu Jul 12 04:05:15 2001
 @@ -38,13 +38,9 @@
  .Fn pfind
  takes a
  .Fa pid
 -has its argument and returns a pointer to the
 +as its argument and returns a pointer to the
  .Vt proc
 -structure whose PID is specified in the argument only if the
 -.Fa pid
 -is on the 
 -.Vt allproc
 -list
 +structure whose PID is specified in the argument.
  .Pp
  .Fn zpfind
  takes a
 @@ -53,9 +49,7 @@
  If
  .Fn zpfind
  finds a process whose PID is equal to that of argument
 -and is a zombie process, meaning that it must reside on the
 -.Vt zombproc
  .Pp
  .Fn zpfind
  takes a
 @@ -53,9 +49,7 @@
  If
  .Fn zpfind
  finds a process whose PID is equal to that of argument
 -and is a zombie process, meaning that it must reside on the
 -.Vt zombproc
 -list
 +and is a zombie process,
  .Fn zpfind
  returns a pointer to that
  .Vt proc
 @@ -80,7 +74,8 @@
  on failure.
  .Sh AUTHORS
  This man page was written by
 -.An Evan Sarmiento (kaworu@sektor7.ath.cx) .
 +.An Evan Sarmiento .
   
 +--lrZ03NoBR/3+SXJZ--
 
 Thank you,
 Evan Sarmiento
 
State-Changed-From-To: open->closed 
State-Changed-By: ru 
State-Changed-When: Mon Jul 16 00:01:27 PDT 2001 
State-Changed-Why:  
Added, thanks! 


Responsible-Changed-From-To: freebsd-doc->ru 
Responsible-Changed-By: ru 
Responsible-Changed-When: Mon Jul 16 00:01:27 PDT 2001 
Responsible-Changed-Why:  

http://www.FreeBSD.org/cgi/query-pr.cgi?pr=28929 
>Unformatted:
