1.\" $OpenBSD: vnsubr.9,v 1.9 2009/03/18 18:26:34 blambert 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: March 18 2009 $ 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. 119See 120.Pa sys/kern/vnode_if.src 121for more details. 122.Pp 123The 124.Fn vn_lock 125function must not be called when the vnode's reference count is 126zero. 127Instead, the 128.Xr vget 9 129function should be used. 130.Pp 131The 132.Fa flags 133argument may contain the following flags: 134.Bl -column LK_INTERLOCK -offset indent 135.It Dv LK_RETRY Ta 136Return the vnode even if it has been reclaimed. 137.It Dv LK_NOWAIT Ta 138Don't wait if the vnode lock is held by someone else (may still 139wait on reclamation lock). 140Must not be used with 141.Dv LK_RETRY . 142.It Dv LK_EXCLUSIVE Ta 143Acquire an exclusive lock. 144.It Dv LK_SHARED Ta 145Acquire a shared lock. 146.El 147.Pp 148The 149.Fn vn_lock 150function can sleep. 151.It Fn vn_marktext "vp" 152Common code to mark the vnode 153.Fa vp 154as being the text of a running process. 155.It Fn vn_open "ndp" "fmode" "cmode" 156Common code for vnode open operations. 157The pathname is described in the 158.Vt nameidata 159pointer (see 160.Xr namei 9 ) . 161The arguments 162.Fa fmode 163and 164.Fa cmode 165specify the 166.Xr open 2 167file mode and the access permissions for creation. 168.Fn vn_open 169checks permissions and invokes the 170.Xr VOP_OPEN 9 171or 172.Xr VOP_CREATE 9 173vnode operations. 174If the operation is successful, zero is returned; 175otherwise an appropriate error code is returned. 176.It Xo 177.Fo vn_rdwr 178.Fa "rw" "vp" "base" "len" "offset" 179.Fa "segflg" "ioflg" "cred" "aresid" "p" 180.Fc 181.Xc 182Common code to package up an I/O request on a vnode into a 183.Vt uio 184and then 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 unlocked vnode is specified by 193.Fa vp . 194The arguments 195.Fa p 196and 197.Fa cred 198are the calling process and its credentials. 199The remaining arguments specify the 200.Vt uio 201parameters. 202For further information on these parameters, see 203.Xr uiomove 9 . 204.It Fn vn_stat "vp" "sb" "p" 205Common code for a vnode stat operation. 206The vnode is specified by the argument 207.Fa vp , 208and 209.Fa sb 210is the buffer in which to store the stat information. 211The argument 212.Fa p 213is the calling process. 214.Fn vn_stat 215basically calls the vnode operation 216.Xr VOP_GETATTR 9 217and transfers the contents of a 218.Vt vattr 219structure into a 220.Vt struct stat . 221If the operation is successful, zero is returned; otherwise an 222appropriate error code is returned. 223.It Fn vn_writechk "vp" 224Common code to check for write permission on the vnode 225.Fa vp . 226A vnode is read-only if it is in use as a process's text image. 227If the vnode is read-only, 228.Er ETXTBSY 229is returned; otherwise zero is 230returned to indicate that the vnode can be written to. 231.El 232.Sh ERRORS 233.Bl -tag -width Er 234.It Bq Er ETXTBSY 235Cannot write to a vnode since it is a process's text image. 236.It Bq Er ENOENT 237The vnode has been reclaimed and is dead. 238This error is only returned if the 239.Dv LK_RETRY 240flag is not passed to 241.Fn vn_lock . 242.It Bq Er EBUSY 243The 244.Dv LK_NOWAIT 245flag was set and 246.Fn vn_lock 247would have slept. 248.El 249.Sh CODE REFERENCES 250This section describes places within the 251.Ox 252source tree where actual code implementing or using the vnode 253framework can be found. 254All pathnames are relative to 255.Pa /usr/src . 256.Pp 257The high-level convenience functions are implemented within the files 258.Pa sys/kern/vfs_vnops.c 259and 260.Pa sys/sys/vnode.h . 261.Sh SEE ALSO 262.Xr file 9 , 263.Xr lock 9 , 264.Xr namei 9 , 265.Xr vfs 9 , 266.Xr vnode 9 , 267.Xr VOP_LOOKUP 9 268.Sh BUGS 269The locking discipline is bizarre. 270Many vnode operations are passed locked vnodes on entry but release 271the lock before they exit. 272Discussions with Kirk McKusick indicate that locking 273discipline evolved out of the pre-VFS way of doing inode locking. 274In addition, the current locking discipline may actually save 275lines of code, especially if the number of file systems is fewer 276than the number of call sites. 277However, the VFS interface would 278require less wizardry if the locking discipline were simpler. 279.Pp 280The locking discipline is used in some places to attempt to make a 281series of operations atomic (e.g., permissions check + 282operation). 283This does not work for non-local file systems that do not 284support locking (e.g., NFS). 285.Pp 286Are vnode locks even necessary? 287The security checks can be moved into the individual file systems. 288Each file system can have the responsibility of ensuring that vnode 289operations are suitably atomic. 290.Pp 291The 292.Dv LK_NOWAIT 293flag does prevent the caller from sleeping. 294.Pp 295The locking discipline as it relates to shared locks has yet to be defined. 296