share/man/man9/vm_page_grab.9

   1 .\"
   2 .\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
   3 .\" Copyright (c) 2013 The FreeBSD Foundation
   4 .\"
   5 .\" Portions of this documentation were written by Konstantin Belousov
   6 .\" under sponsorship from the FreeBSD Foundation.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice(s), this list of conditions and the following disclaimer as
  13 .\"    the first lines of this file unmodified other than the possible
  14 .\"    addition of one or more copyright notices.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice(s), this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  20 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  21 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  22 .\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
  23 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  24 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  25 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  26 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  29 .\" DAMAGE.
  30 .\"
  31 .\" $FreeBSD$
  32 .\"
  33 .Dd August 23, 2013
  34 .Dt VM_PAGE_GRAB 9
  35 .Os
  36 .Sh NAME
  37 .Nm vm_page_grab
  38 .Nd "returns a page from an object"
  39 .Sh SYNOPSIS
  40 .In sys/param.h
  41 .In vm/vm.h
  42 .In vm/vm_page.h
  43 .Ft vm_page_t
  44 .Fn vm_page_grab "vm_object_t object" "vm_pindex_t pindex" "int allocflags"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn vm_page_grab
  48 function returns the page at
  49 .Fa pindex
  50 from the given object.
  51 If the page exists and is busy,
  52 .Fn vm_page_grab
  53 will sleep while waiting for it.
  54 If the page does not exist, it is allocated.
  55 The function sleeps until the allocation request can be satisfied.
  56 .Pp
  57 The function requires the
  58 .Fa object
  59 to be locked on entry, and returns with the object locked.
  60 If the
  61 .Fn vm_page_grab
  62 function sleeps for any reason, the object lock is temporary dropped.
  63 .Pp
  64 The
  65 .Fn vm_page_grab
  66 supports all of the flags supported by
  67 .Xr vm_page_alloc 9 .
  68 In addition,
  69 .Fn vm_page_grab
  70 supports the following flags:
  71 .Bl -tag -width ".Dv VM_ALLOC_IGN_SBUSY"
  72 .It Dv VM_ALLOC_IGN_SBUSY
  73 When waiting for the busy state of the existing page to drain,
  74 only test for exclusive busy; ignore the shared busy counter.
  75 .El
  76 .Sh RETURN VALUES
  77 The
  78 .Fn vm_page_grab
  79 always returns the page.
  80 .Sh SEE ALSO
  81 .Xr vm_page_alloc 9
  82 .Sh AUTHORS
  83 This manual page was written by
  84 .An Chad David Aq davidc@acns.ab.ca .