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