svn commit: r254673 - head/share/man/man9

[Konstantin Belousov]

Author: kib
Date: Thu Aug 22 22:01:56 2013
New Revision: 254673
URL: http://svnweb.freebsd.org/changeset/base/254673

Log:
  Update the manual page for vm_page_grab(9).
  
  Reviewed and edited by:	alc
  Sponsored by:	The FreeBSD Foundation

Modified:
  head/share/man/man9/vm_page_grab.9

Modified: head/share/man/man9/vm_page_grab.9
==============================================================================
--- head/share/man/man9/vm_page_grab.9	Thu Aug 22 20:29:57 2013	(r254672)
+++ head/share/man/man9/vm_page_grab.9	Thu Aug 22 22:01:56 2013	(r254673)
@@ -1,5 +1,9 @@
 .\"
 .\" Copyright (C) 2001 Chad David <davidc at acns.ab.ca>. All rights reserved.
+.\" Copyright (c) 2013 The FreeBSD Foundation
+.\"
+.\" Portions of this documentation were written by Konstantin Belousov
+.\" under sponsorship from the FreeBSD Foundation.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -26,7 +30,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd August 7, 2001
+.Dd August 23, 2013
 .Dt VM_PAGE_GRAB 9
 .Os
 .Sh NAME
@@ -48,21 +52,31 @@ If the page exists and is busy,
 .Fn vm_page_grab
 will sleep while waiting for it.
 If the page does not exist, it is allocated.
+The function sleeps until the allocation request can be satisfied.
+.Pp
+The function requires the
+.Fa object
+to be locked on entry, and returns with the object locked.
+If the
+.Fn vm_page_grab
+function sleeps for any reason, the object lock is temporary dropped.
 .Pp
-If
-.Dv VM_ALLOC_RETRY
-is not set in
-.Fa allocflags
-and the function sleeps, either getting the page from the object
-or while allocating it,
-.Dv NULL
-is returned.
+The
+.Fn vm_page_grab
+supports all of the flags supported by
+.Xr vm_page_alloc .
+In addition,
+.Fn vm_page_grab
+supports the following flags:
+.Bl -tag -width ".Dv VM_ALLOC_IGN_SBUSY"
+.It Dv VM_ALLOC_IGN_SBUSY
+When waiting for the busy state of the existing page to drain,
+only test for exclusive busy; ignore the shared busy counter.
+.El
 .Sh RETURN VALUES
-If successful,
+The
 .Fn vm_page_grab
-returns the page; otherwise,
-.Dv NULL
-is returned.
+always returns the page.
 .Sh SEE ALSO
 .Xr vm_page_alloc 9
 .Sh AUTHORS