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