1.\" $OpenBSD: vnsubr.9,v 1.13 2016/06/19 16:06:18 jmc Exp $ 2.\" $NetBSD: vnsubr.9,v 1.21 2004/05/25 14:54:56 hannken Exp $ 3.\" 4.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Gregory McGarry. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: June 19 2016 $ 32.Dt VNSUBR 9 33.Os 34.Sh NAME 35.Nm vnsubr , 36.Nm vn_close , 37.Nm vn_default_error , 38.Nm vn_isunder , 39.Nm vn_lock , 40.Nm vn_marktext , 41.Nm vn_rdwr , 42.Nm vn_open , 43.Nm vn_stat , 44.Nm vn_writechk 45.Nd high-level convenience functions for vnode operations 46.Sh SYNOPSIS 47.In sys/param.h 48.In sys/lock.h 49.In sys/vnode.h 50.Ft int 51.Fn vn_close "struct vnode *vp" "int flags" "struct ucred *cred" "struct proc *p" 52.Ft int 53.Fn vn_default_error "void *v" 54.Ft int 55.Fn vn_isunder "struct vnode *dvp" "struct vnode *rvp" "struct proc *p" 56.Ft int 57.Fn vn_lock "struct vnode *vp" "int flags" "struct proc *p" 58.Ft void 59.Fn vn_marktext "struct vnode *vp" 60.Ft int 61.Fn vn_open "struct nameidata *ndp" "int fmode" "int cmode" 62.Ft int 63.Fo vn_rdwr 64.Fa "enum uio_rw rw" "struct vnode *vp" "caddr_t base" 65.Fa "int len" "off_t offset" "enum uio_seg segflg" "int ioflg" 66.Fa "struct ucred *cred" "size_t *aresid" "struct proc *p" 67.Fc 68.Ft int 69.Fn vn_stat "struct vnode *vp" "struct stat *sb" "struct proc *p" 70.Ft int 71.Fn vn_writechk "struct vnode *vp" 72.Sh DESCRIPTION 73The high-level functions described in this page are convenience 74functions for simplified access to the vnode operations described in 75.Xr VOP_LOOKUP 9 . 76.Bl -tag -width Ds 77.It Fn vn_close "vp" "flags" "cred" "p" 78Common code for a vnode close. 79The argument 80.Fa vp 81is the unlocked vnode of the vnode to close. 82.Fn vn_close 83simply locks the vnode, invokes the vnode operation 84.Fn VOP_CLOSE 85and calls 86.Xr vput 9 87to return the vnode to the freelist or holdlist. 88Note that 89.Fn vn_close 90expects an unlocked, referenced vnode and will dereference the vnode 91prior to returning. 92If the operation is successful, zero is returned; 93otherwise an appropriate error is returned. 94.It Fn vn_default_error "v" 95A generic "default" routine that just returns error. 96It is used by a file system to specify unsupported operations in 97the vnode operations vector. 98.It Fn vn_isunder "dvp" "rvp" "p" 99Common code to check if one directory specified by the vnode 100.Fa rvp 101can be found inside the directory specified by the vnode 102.Fa dvp . 103The argument 104.Fa p 105is the calling process. 106.Fn vn_isunder 107is intended to be used in 108.Xr chroot 2 , 109.Xr chdir 2 , 110.Xr fchdir 2 , 111etc., to ensure that 112.Xr chroot 2 113actually means something. 114If the operation is successful, zero is returned; otherwise 1 is returned. 115.It Fn vn_lock "vp" "flags" "p" 116Acquire the vnode lock. 117Certain file system operations require that 118the vnode lock be held when they are called. 119.Pp 120The 121.Fn vn_lock 122function must not be called when the vnode's reference count is 123zero. 124Instead, the 125.Xr vget 9 126function should be used. 127.Pp 128In addition to the 129.Fa flags 130accepted by 131.Xr VOP_LOCK 9 , 132the 133.Dv LK_RETRY 134flag may be used. 135.Dv LK_RETRY 136causes 137.Fn vn_lock 138to return the vnode even if it has been reclaimed. 139It must not be used with 140.Dv LK_NOWAIT . 141.Pp 142The 143.Fn vn_lock 144function can sleep. 145.It Fn vn_marktext "vp" 146Common code to mark the vnode 147.Fa vp 148as being the text of a running process. 149.It Fn vn_open "ndp" "fmode" "cmode" 150Common code for vnode open operations. 151The pathname is described in the 152.Vt nameidata 153pointer (see 154.Xr namei 9 ) . 155The arguments 156.Fa fmode 157and 158.Fa cmode 159specify the 160.Xr open 2 161file mode and the access permissions for creation. 162.Fn vn_open 163checks permissions and invokes the 164.Xr VOP_OPEN 9 165or 166.Xr VOP_CREATE 9 167vnode operations. 168If the operation is successful, zero is returned; 169otherwise an appropriate error code is returned. 170.It Xo 171.Fo vn_rdwr 172.Fa "rw" "vp" "base" "len" "offset" 173.Fa "segflg" "ioflg" "cred" "aresid" "p" 174.Fc 175.Xc 176Common code to package up an I/O request on a vnode into a 177.Vt uio 178and then perform the I/O. 179The argument 180.Fa rw 181specifies whether the I/O is a read 182.Pq Dv UIO_READ 183or write 184.Pq Dv UIO_WRITE 185operation. 186The unlocked vnode is specified by 187.Fa vp . 188The arguments 189.Fa p 190and 191.Fa cred 192are the calling process and its credentials. 193The remaining arguments specify the 194.Vt uio 195parameters. 196For further information on these parameters, see 197.Xr uiomove 9 . 198.It Fn vn_stat "vp" "sb" "p" 199Common code for a vnode stat operation. 200The vnode is specified by the argument 201.Fa vp , 202and 203.Fa sb 204is the buffer in which to store the stat information. 205The argument 206.Fa p 207is the calling process. 208.Fn vn_stat 209basically calls the vnode operation 210.Xr VOP_GETATTR 9 211and transfers the contents of a 212.Vt vattr 213structure into a 214.Vt struct stat . 215If the operation is successful, zero is returned; otherwise an 216appropriate error code is returned. 217.It Fn vn_writechk "vp" 218Common code to check for write permission on the vnode 219.Fa vp . 220A vnode is read-only if it is in use as a process's text image. 221If the vnode is read-only, 222.Er ETXTBSY 223is returned; otherwise zero is 224returned to indicate that the vnode can be written to. 225.El 226.Sh ERRORS 227.Bl -tag -width Er 228.It Bq Er ETXTBSY 229Cannot write to a vnode since it is a process's text image. 230.It Bq Er ENOENT 231The vnode has been reclaimed and is dead. 232This error is only returned if the 233.Dv LK_RETRY 234flag is not passed to 235.Fn vn_lock . 236.It Bq Er EBUSY 237The 238.Dv LK_NOWAIT 239flag was set and 240.Fn vn_lock 241would have slept. 242.El 243.Sh CODE REFERENCES 244This section describes places within the 245.Ox 246source tree where actual code implementing or using the vnode 247framework can be found. 248All pathnames are relative to 249.Pa /usr/src . 250.Pp 251The high-level convenience functions are implemented within the files 252.Pa sys/kern/vfs_vnops.c 253and 254.Pa sys/sys/vnode.h . 255.Sh SEE ALSO 256.Xr file 9 , 257.Xr namei 9 , 258.Xr vfs 9 , 259.Xr vnode 9 , 260.Xr VOP_LOOKUP 9 261.Sh BUGS 262The locking discipline is bizarre. 263Many vnode operations are passed locked vnodes on entry but release 264the lock before they exit. 265Discussions with Kirk McKusick indicate that locking 266discipline evolved out of the pre-VFS way of doing inode locking. 267In addition, the current locking discipline may actually save 268lines of code, especially if the number of file systems is fewer 269than the number of call sites. 270However, the VFS interface would 271require less wizardry if the locking discipline were simpler. 272.Pp 273The locking discipline is used in some places to attempt to make a 274series of operations atomic (e.g., permissions check + 275operation). 276This does not work for non-local file systems that do not 277support locking (e.g., NFS). 278.Pp 279Are vnode locks even necessary? 280The security checks can be moved into the individual file systems. 281Each file system can have the responsibility of ensuring that vnode 282operations are suitably atomic. 283.Pp 284The 285.Dv LK_NOWAIT 286flag does prevent the caller from sleeping. 287.Pp 288The locking discipline as it relates to shared locks has yet to be defined. 289