/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.Dt VOP_CREATEVOBJECT 9
 29.Os
 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
 45These calls are used to control the association of a VM object
 46with a particular vnode.
 47.Pp
 48The arguments specific to these functions are:
 49.Bl -tag -width objpp
 50.It Fa vp
 51The vnode of the file.
 52.It Fa objpp
 53The VM object being returned, or
 54.Dv NULL
 55if the caller wants to test for the existence
 56of the VM object.
 57.El
 58.Pp
 59.Xr VFS 9
 60invokes
 61.Fn VOP_CREATEVOBJECT
 62when it needs to create a VM object for the given
 63.Xr vnode 9 .
 64File system code may pass this call down to the underlying file system.
 65This VOP can be called multiple times,
 66and file system code should ignore any additional calls,
 67exiting with a zero return code.
 68.Pp
 69.Fn VOP_DESTROYVOBJECT
 70is called when a
 71.Xr vnode 9
 72is recycled.
 73.Pp
 74.Fn VOP_GETVOBJECT
 75should be used by all kernel code to get a VM object.
 76.\" XXX What is the next sentence trying to tell people?
 77The returned VM object may belong to a different file system in the case
 78of stacked mounts.
 79.Pp
 80.Xr VFS 9
 81has three functions which perform standard operations by creating
 82and destroying VM objects.
 83These functions are:
 84.Fn vop_stdcreatevobject ,
 85.Fn vop_stddestroyvobject
 86and
 87.Fn vop_stdgetvobject .
 88.Pp
 89.Em Note :
 90a
 91.Xr vnode 9
 92should be locked on entry and must be left locked on exit.
 93.Sh RETURN VALUES
 94The
 95.Fn VOP_CREATEVOBJECT ,
 96.Fn VOP_DESTROYVOBJECT
 97and
 98.Fn VOP_GETVOBJECT
 99functions return zero on success, or a non-zero value on failure.
100Zero 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?
104By default, file systems leave VM object handling to the
105.Fn vop_std*
106functions.
107.Sh SEE ALSO
108.Xr vnode 9 ,
109.Xr VOP_GETPAGES 9 ,
110.Xr VOP_PUTPAGES 9
111.Sh AUTHORS
112This manual page was written by
113.An Boris Popov .