1.\" $NetBSD: vnsubr.9,v 1.12 2002/10/20 10:37:36 wiz Exp $ 2.\" 3.\" Copyright (c) 2001 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 22, 2001 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.Fd #include \*[Lt]sys/param.h\*[Gt] 58.Fd #include \*[Lt]sys/lock.h\*[Gt] 59.Fd #include \*[Lt]sys/vnode.h\*[Gt] 60.Ft int 61.Fn vn_bwrite "void *ap" 62.Ft int 63.Fn vn_close "struct vnode *vp" "int flags" "struct ucred *cred" "struct proc *p" 64.Ft int 65.Fn vn_default_error "void *v" 66.Ft int 67.Fn vn_isunder "struct vnode *dvp" "struct vnode *rvp" "struct proc *p" 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" "caddr_t base" 83.Fa "int len" "off_t offset" "enum uio_seg segflg" "int ioflg" 84.Fa "struct ucred *cred" "size_t *aresid" "struct proc *p" 85.Fc 86.Ft int 87.Fn vn_readdir "struct file *fp" "char *buf" "int segflg" "u_int count" "int *done" "struct proc *p" "off_t **cookies" "int *ncookies" 88.Ft int 89.Fn vn_stat "struct vnode *vp" "struct stat *sb" "struct proc *p" 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 simplied 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" "p" 101Common code for a vnode close. 102The argument 103.Fa vp 104is the locked 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" "p" 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 p 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 releases 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 Fo vn_rdwr 197.Fa "rw" "vp" "base" "len" "offset" "segflg" "ioflg" 198.Fa "cred" "aresid" "p" 199.Fc 200Common code to package up an I/O request on a vnode into a uio and 201then perform the I/O. 202The argument 203.Fa rw 204specifies whether the I/O is a read (UIO_READ) or write (UIO_WRITE) 205operation. 206The unlocked vnode is specified by 207.Fa vp . 208The arguments 209.Fa p 210and 211.Fa cred 212are the calling process and its credentials. 213The remaining arguments specify the uio parameters. 214For further information on these parameters see 215.Xr uiomove 9 . 216.It Fo vn_readdir 217.Fa "fp" "buf" "segflg" "count" "done" "p" "cookies" 218.Fa "ncookies" 219.Fc 220Common code for reading the contents of a directory. 221The argument 222.Fa fp 223is the file structure, 224.Fa buf 225is the buffer for placing the struct dirent structures. 226The arguments 227.Fa cookies 228and 229.Fa ncookies 230specify the addresses for the list and number of directory seek 231cookies generated for NFS. 232Both 233.Fa cookies 234and 235.Fa ncookies 236should be NULL is they aren't required to be returned by 237.Fn vn_readdir . 238If the operation is successful zero is returned, otherwise an 239appropriate error code is returned. 240.It Fn vn_stat "vp" "sb" "p" 241Common code for a vnode stat operation. 242The vnode is specified by the argument 243.Fa vp 244and 245.Fa sb 246is the buffer to return the stat information. 247The argument 248.Fa p 249is the calling process. 250.Fn vn_stat 251basically calls the vnode operation 252.Xr VOP_GETATTR 9 253and transfer the contents of a vattr structure into a struct stat. 254If the operation is successful zero is returned, otherwise an 255appropriate error code is returned. 256.It Fn vn_writechk "vp" 257Common code to check for write permission on the vnode 258.Fa vp . 259A vnode is read-only if it is in use as a process's text image. 260If the vnode is read-only ETEXTBSY is returned, otherwise zero is 261returned to indicate that the vnode can be written to. 262.El 263.Sh ERRORS 264.Bl -tag -width Er 265.It Bq Er ETXTBSY 266Cannot write to a vnode since is a process's text image. 267.It Bq Er ENOENT 268The vnode has been reclaimed and is dead. 269This error is only returned if the LK_RETRY flag is not passed to 270.Fn vn_lock . 271.It Bq Er EBUSY 272The LK_NOWAIT flag was set and 273.Fn vn_lock 274would have slept. 275.El 276.Sh CODE REFERENCES 277This section describes places within the 278.Nx 279source tree where actual code implementing or utilising the vnode 280framework can be found. 281All pathnames are relative to 282.Pa /usr/src . 283.Pp 284The high-level convenience functions are implemented within the file 285.Pa sys/kern/vfs_vnops.c . 286.Sh SEE ALSO 287.Xr file 9 , 288.Xr intro 9 , 289.Xr lock 9 , 290.Xr namei 9 , 291.Xr vattr 9 , 292.Xr vfs 9 , 293.Xr vnode 9 , 294.Xr vnodeops 9 295