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