From davidc@acns.ab.ca  Fri Nov 23 21:39:45 2001
Return-Path: <davidc@acns.ab.ca>
Received: from mail.acns.ab.ca (h24-64-56-135.cg.shawcable.net [24.64.56.135])
	by hub.freebsd.org (Postfix) with ESMTP id 03FB737B417
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 23 Nov 2001 21:39:45 -0800 (PST)
Received: from colnta.acns.ab.ca (colnta.acns.ab.ca [192.168.1.2])
	by mail.acns.ab.ca (8.11.6/8.11.3) with ESMTP id fAO5dcb87276
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 23 Nov 2001 22:39:38 -0700 (MST)
	(envelope-from davidc@colnta.acns.ab.ca)
Received: (from davidc@localhost)
	by colnta.acns.ab.ca (8.11.6/8.11.3) id fAO5dcr86823;
	Fri, 23 Nov 2001 22:39:38 -0700 (MST)
	(envelope-from davidc)
Message-Id: <200111240539.fAO5dcr86823@colnta.acns.ab.ca>
Date: Fri, 23 Nov 2001 22:39:38 -0700 (MST)
From: Chad David <davidc@acns.ab.ca>
Reply-To: Chad David <davidc@acns.ab.ca>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: vm_page_alloc.9 rewrite 
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         32241
>Category:       docs
>Synopsis:       vm_page_alloc.9 rewrite
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    davidc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Nov 23 21:40:01 PST 2001
>Closed-Date:    Wed Jan 9 01:06:17 PST 2002
>Last-Modified:  Wed Jan 09 01:08:40 PST 2002
>Originator:     Chad David
>Release:        FreeBSD 5.0-CURRENT i386
>Organization:
ACNS Inc. 
>Environment:
System: FreeBSD colnta 4.4-STABLE FreeBSD 4.4-STABLE #9: Tue Nov 20 16:38:27 MST 2001 davidc@colnta:/mnt1/obj/usr/src/sys/COLNTA i386


	
>Description:
The vm_page_alloc.9 man page is crap (I'm allowed to say that
because I wrote it).
>How-To-Repeat:
man vm_page_alloc
>Fix:
Apply this patch.


--- ../../src/share/man/man9/vm_page_alloc.9	Wed Jul 18 00:09:13 2001
+++ vm_page_alloc.9	Fri Nov 23 22:02:59 2001
@@ -31,7 +31,7 @@
 .Os
 .Sh NAME
 .Nm vm_page_alloc
-.Nd "allocates a page for the object and index"
+.Nd "allocate a page for a vm_object"
 .Sh SYNOPSIS
 .In sys/param.h
 .In vm/vm.h
@@ -41,34 +41,36 @@
 .Sh DESCRIPTION
 The
 .Fn vm_page_alloc
-function allocates a page for
-.Fa pindex
-in the VM object
-.Fa object .
-It is assumed that a page has not already been allocated for
+function allocates a page at
 .Fa pindex
-and
+within
 .Fa object .
+It is assumed that a page has not already been allocated at
+.Fa pindex .
+The page returned is inserted into the object, but is not inserted
+into the pmap.
 .Pp
-The
 .Fn vm_page_alloc
-function will not block.
+will not block.
 .Pp
 Its arguments are:
 .Bl -tag -width ".Fa page_req"
 .It Fa object
 The VM object to allocate the page for.
 .It Fa pindex
-The index of the page that should be allocated.
+The index into the object at which the page should be inserted.
 .It Fa page_req
 A flag indicating how the page should be allocated.
 .Bl -tag -width ".Dv VM_ALLOC_INTERRUPT"
 .It Dv VM_ALLOC_NORMAL
 The page should be allocated with no special treatment.
 .It Dv VM_ALLOC_SYSTEM
-The page can be allocated even if the buffer cache queue is empty
-and the free count is above the interrupt reserved water mark.
-This should be used only when the system really needs the page.
+The page can be allocated if the cache is empty and the free page
+count is above the interrupt reserved water mark.  If
+.Dv VM_ALLOC_INTERRUPT
+is set the page can be allocated as long as the free page count is
+greater than zero.
+This flag should be used only when the system really needs the page.
 .It Dv VM_ALLOC_INTERRUPT
 .Fn vm_page_alloc
 is being called during an interrupt and therefore the cache cannot

>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->davidc 
Responsible-Changed-By: dd 
Responsible-Changed-When: Sun Jan 6 23:02:54 PST 2002 
Responsible-Changed-Why:  
Over to originator. 

http://www.FreeBSD.org/cgi/query-pr.cgi?pr=32241 
State-Changed-From-To: open->closed 
State-Changed-By: davidc 
State-Changed-When: Wed Jan 9 01:06:17 PST 2002 
State-Changed-Why:  
Applied the supplied patch (plus some minor changes) to revision 
1.2 of src/share/man/man9/vm_page_alloc.9. 

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