share/man/man9/VOP_GETVOBJECT.9

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 2000 Boris Popov
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  15 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  16 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  17 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  18 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  19 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  20 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  21 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  23 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd September 10, 2000
  28 .Os
  29 .Dt VOP_CREATEVOBJECT 9
  30 .Sh NAME
  31 .Nm VOP_CREATEVOBJECT ,
  32 .Nm VOP_DESTROYVOBJECT ,
  33 .Nm VOP_GETVOBJECT
  34 .Nd VM object interaction
  35 .Sh SYNOPSIS
  36 .In sys/param.h
  37 .In sys/vnode.h
  38 .Ft int
  39 .Fn VOP_CREATEVOBJECT "struct vnode *vp" "struct ucred *cred" "struct thread *td"
  40 .Ft int
  41 .Fn VOP_DESTROYVOBJECT "struct vnode *vp"
  42 .Ft int
  43 .Fn VOP_GETVOBJECT "struct vnode *vp" "struct vm_object **objpp"
  44 .Sh DESCRIPTION
  45 These calls are used to control the association of a VM object
  46 with a particular vnode.
  47 .Pp
  48 The arguments specific to these functions are:
  49 .Bl -tag -width objpp
  50 .It Fa vp
  51 The vnode of the file.
  52 .It Fa objpp
  53 The VM object being returned, or
  54 .Dv NULL
  55 if the caller wants to test for the existence
  56 of the VM object).
  57 .El
  58 .Pp
  59 .Xr VFS 9
  60 invokes
  61 .Fn VOP_CREATEVOBJECT
  62 when it needs to create a VM object for the given
  63 .Xr vnode 9 .
  64 File system code may pass this call down to the underlying file system.
  65 This VOP can be called multiple times,
  66 and file system code should ignore any additional calls,
  67 exiting with a zero return code.
  68 .Pp
  69 .Fn VOP_DESTROYVOBJECT
  70 is called when a
  71 .Xr vnode 9
  72 is recycled.
  73 .Pp
  74 .Fn VOP_GETVOBJECT
  75 should be used by all kernel code to get a VM object.
  76 .\" XXX What is the next sentence trying to tell people?
  77 The returned VM object may belong to a different file system in the case
  78 of stacked mounts.
  79 .Pp
  80 .Xr VFS 9
  81 has three functions which perform standard operations by creating
  82 and destroying VM objects.
  83 These functions are:
  84 .Fn vop_stdcreatevobject ,
  85 .Fn vop_stddestroyvobject
  86 and
  87 .Fn vop_stdgetvobject .
  88 .Pp
  89 .Em Note :
  90 a
  91 .Xr vnode 9
  92 should be locked on entry and must be left locked on exit.
  93 .Sh RETURN VALUES
  94 The
  95 .Fn VOP_CREATEVOBJECT ,
  96 .Fn VOP_DESTROYVOBJECT
  97 and
  98 .Fn VOP_GETVOBJECT
  99 functions return zero on success, or a non-zero value on failure.
 100 Zero is returned on success, otherwise an error is returned.
 101 .Sh EXAMPLES
 102 .\" XXX Why is this code here when it does not use the functions
 103 .\" described in this manual page?
 104 By default, file systems leave VM object handling to the
 105 .Fn vop_std*
 106 functions.
 107 .Sh SEE ALSO
 108 .Xr vnode 9 ,
 109 .Xr VOP_GETPAGES 9 ,
 110 .Xr VOP_PUTPAGES 9
 111 .Sh AUTHORS
 112 This manual page was written by
 113 .An Boris Popov .