Update the manual page for vm_page_grab(9).

Reviewed and edited by:	alc
Sponsored by:	The FreeBSD Foundation

share/man/man9/vm_page_grab.9

@@ -1,5 +1,9 @@
 .\"
 .\" Copyright (C) 2001 Chad David <davidc@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
-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.
-.Sh RETURN VALUES
-If successful,
+The function requires the
+.Fa object
+to be locked on entry, and returns with the object locked.
+If the
 .Fn vm_page_grab
-returns the page; otherwise,
-.Dv NULL
-is returned.
+function sleeps for any reason, the object lock is temporary dropped.
+.Pp
+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
+The
+.Fn vm_page_grab
+always returns the page.
 .Sh SEE ALSO
 .Xr vm_page_alloc 9
 .Sh AUTHORS