1.\" $NetBSD: vnsubr.9,v 1.32 2007/10/08 10:32:38 hannken Exp $ 2.\" 3.\" Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Gregory McGarry. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd October 7, 2007 38.Dt VNSUBR 9 39.Os 40.Sh NAME 41.Nm vnsubr , 42.Nm vn_bwrite , 43.Nm vn_close , 44.Nm vn_default_error , 45.Nm vn_isunder , 46.Nm vn_lock , 47.Nm vn_markexec , 48.Nm vn_marktext , 49.Nm vn_rdwr , 50.Nm vn_restorerecurse , 51.Nm vn_setrecurse , 52.Nm vn_open , 53.Nm vn_stat , 54.Nm vn_writechk 55.Nd high-level convenience functions for vnode operations 56.Sh SYNOPSIS 57.In sys/param.h 58.In sys/lock.h 59.In sys/vnode.h 60.Ft int 61.Fn vn_bwrite "void *ap" 62.Ft int 63.Fn vn_close "struct vnode *vp" "int flags" "kauth_cred_t cred" "struct lwp *l" 64.Ft int 65.Fn vn_default_error "void *v" 66.Ft int 67.Fn vn_isunder "struct vnode *dvp" "struct vnode *rvp" "struct lwp *l" 68.Ft int 69.Fn vn_lock "struct vnode *vp" "int flags" 70.Ft void 71.Fn vn_markexec "struct vnode *vp" 72.Ft void 73.Fn vn_marktext "struct vnode *vp" 74.Ft u_int 75.Fn vn_setrecurse "struct vnode *vp" 76.Ft void 77.Fn vn_restorerecurse "struct vnode *vp" "u_int flags" 78.Ft int 79.Fn vn_open "struct nameidata *ndp" "int fmode" "int cmode" 80.Ft int 81.Fo vn_rdwr 82.Fa "enum uio_rw rw" "struct vnode *vp" "void *base" 83.Fa "int len" "off_t offset" "enum uio_seg segflg" "int ioflg" 84.Fa "kauth_cred_t cred" "size_t *aresid" "struct lwp *l" 85.Fc 86.Ft int 87.Fn vn_readdir "struct file *fp" "char *buf" "int segflg" "u_int count" "int *done" "struct lwp *l" "off_t **cookies" "int *ncookies" 88.Ft int 89.Fn vn_stat "struct vnode *vp" "struct stat *sb" "struct lwp *l" 90.Ft int 91.Fn vn_writechk "struct vnode *vp" 92.Sh DESCRIPTION 93The high-level functions described in this page are convenience 94functions for simplified access to the vnode operations described in 95.Xr vnodeops 9 . 96.Sh FUNCTIONS 97.Bl -tag -width compact 98.It Fn vn_bwrite "ap" 99Common code for block write operations. 100.It Fn vn_close "vp" "flags" "cred" "l" 101Common code for a vnode close. 102The argument 103.Fa vp 104is the unlocked vnode of the vnode to close. 105.Fn vn_close 106simply locks the vnode, invokes the vnode operation 107.Xr VOP_CLOSE 9 108and calls 109.Fn vput 110to return the vnode to the freelist or holdlist. 111Note that 112.Fn vn_close 113expects an unlocked, referenced vnode and will dereference the vnode 114prior to returning. 115If the operation is successful zero is returned, 116otherwise an appropriate error is returned. 117.It Fn vn_default_error "v" 118A generic "default" routine that just returns error. 119It is used by a file system to specify unsupported operations in 120the vnode operations vector. 121.It Fn vn_isunder "dvp" "rvp" "l" 122Common code to check if one directory specified by the vnode 123.Fa rvp 124can be found inside the directory specified by the vnode 125.Fa dvp . 126The argument 127.Fa l 128is the calling process. 129.Fn vn_isunder 130is intended to be used in 131.Xr chroot 2 , 132.Xr chdir 2 , 133.Xr fchdir 2 , 134etc., to ensure that 135.Xr chroot 2 136actually means something. 137If the operation is successful zero is returned, otherwise 1 is returned. 138.It Fn vn_lock "vp" "flags" 139Common code to acquire the lock for vnode 140.Fa vp . 141The argument 142.Fa flags 143specifies the 144.Xr lockmgr 9 145flags used to lock the vnode. 146If the operation is successful zero is returned, otherwise an 147appropriate error code is returned. 148The vnode interlock 149.Em v_interlock 150is released on return. 151.Pp 152.Fn vn_lock 153must not be called when the vnode's reference count is zero. 154Instead, 155.Xr vget 9 156should be used. 157.It Fn vn_markexec "vp" 158Common code to mark the vnode 159.Fa vp 160as containing executable code of a running process. 161.It Fn vn_marktext "vp" 162Common code to mark the vnode 163.Fa vp 164as being the text of a running process. 165.It Fn vn_setrecurse "vp" 166Common code to enable LK_CANRECURSE on the vnode lock for vnode 167.Fa vp . 168.Fn vn_setrecurse 169returns the new 170.Xr lockmgr 9 171flags after the update. 172.It Fn vn_restorerecurse "vp" "flags" 173Common code to restore the vnode lock flags for the vnode 174.Fa vp . 175It is called when done with 176.Fn vn_setrecurse . 177.It Fn vn_open "ndp" "fmode" "cmode" 178Common code for vnode open operations. 179The pathname is described in the nameidata pointer (see 180.Xr namei 9 ) . 181The arguments 182.Fa fmode 183and 184.Fa cmode 185specify the 186.Xr open 2 187file mode and the access permissions for creation. 188.Fn vn_open 189checks permissions and invokes the 190.Xr VOP_OPEN 9 191or 192.Xr VOP_CREATE 9 193vnode operations. 194If the operation is successful zero is returned, 195otherwise an appropriate error code is returned. 196.It Fn vn_rdwr "rw" "vp" "base" "len" "offset" "segflg" "ioflg" "cred" "aresid" "l" 197Common code to package up an I/O request on a vnode into a uio and 198then perform the I/O. 199The argument 200.Fa rw 201specifies whether the I/O is a read (UIO_READ) or write (UIO_WRITE) 202operation. 203The unlocked vnode is specified by 204.Fa vp . 205The arguments 206.Fa l 207and 208.Fa cred 209are the calling lwp and its credentials. 210The remaining arguments specify the uio parameters. 211For further information on these parameters see 212.Xr uiomove 9 . 213.It Fn vn_readdir "fp" "buf" "segflg" "count" "done" "l" "cookies" "ncookies" 214Common code for reading the contents of a directory. 215The argument 216.Fa fp 217is the file structure, 218.Fa buf 219is the buffer for placing the struct dirent structures. 220The arguments 221.Fa cookies 222and 223.Fa ncookies 224specify the addresses for the list and number of directory seek 225cookies generated for NFS. 226Both 227.Fa cookies 228and 229.Fa ncookies 230should be NULL is they aren't required to be returned by 231.Fn vn_readdir . 232If the operation is successful zero is returned, otherwise an 233appropriate error code is returned. 234.It Fn vn_stat "vp" "sb" "l" 235Common code for a vnode stat operation. 236The vnode is specified by the argument 237.Fa vp , 238and 239.Fa sb 240is the buffer to return the stat information. 241The argument 242.Fa l 243is the calling lwp. 244.Fn vn_stat 245basically calls the vnode operation 246.Xr VOP_GETATTR 9 247and transfers the contents of a vattr structure into a struct stat. 248If the operation is successful zero is returned, otherwise an 249appropriate error code is returned. 250.It Fn vn_writechk "vp" 251Common code to check for write permission on the vnode 252.Fa vp . 253A vnode is read-only if it is in use as a process's text image. 254If the vnode is read-only ETEXTBSY is returned, otherwise zero is 255returned to indicate that the vnode can be written to. 256.El 257.Sh ERRORS 258.Bl -tag -width Er 259.It Bq Er EBUSY 260The LK_NOWAIT flag was set and 261.Fn vn_lock 262would have slept. 263.It Bq Er ENOENT 264The vnode has been reclaimed and is dead. 265This error is only returned if the LK_RETRY flag is not passed to 266.Fn vn_lock . 267.It Bq Er ETXTBSY 268Cannot write to a vnode since is a process's text image. 269.El 270.Sh CODE REFERENCES 271This section describes places within the 272.Nx 273source tree where actual code implementing or using the vnode 274framework can be found. 275All pathnames are relative to 276.Pa /usr/src . 277.Pp 278The high-level convenience functions are implemented within the files 279.Pa sys/kern/vfs_vnops.c 280and 281.Pa sys/sys/vnode.h . 282.Sh SEE ALSO 283.Xr file 9 , 284.Xr intro 9 , 285.Xr lock 9 , 286.Xr namei 9 , 287.Xr vattr 9 , 288.Xr vfs 9 , 289.Xr vnode 9 , 290.Xr vnodeops 9 291