1.\" $NetBSD: vnsubr.9,v 1.47 2019/11/17 11:46:38 wiz Exp $ 2.\" 3.\" Copyright (c) 2001, 2005, 2006 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd January 2, 2017 31.Dt VNSUBR 9 32.Os 33.Sh NAME 34.Nm vnsubr , 35.Nm vn_bwrite , 36.Nm vn_close , 37.Nm vn_default_error , 38.Nm vn_isunder , 39.Nm vn_lock , 40.Nm vn_markexec , 41.Nm vn_marktext , 42.Nm vn_rdwr , 43.Nm vn_open , 44.Nm vn_bdev_open , 45.Nm vn_bdev_openpath , 46.Nm vn_stat , 47.Nm vn_writechk 48.Nd high-level convenience functions for vnode operations 49.Sh SYNOPSIS 50.In sys/param.h 51.In sys/lock.h 52.In sys/vnode.h 53.Ft int 54.Fn vn_bwrite "void *ap" 55.Ft int 56.Fn vn_close "struct vnode *vp" "int flags" "kauth_cred_t cred" 57.Ft int 58.Fn vn_default_error "void *v" 59.Ft int 60.Fn vn_isunder "struct vnode *dvp" "struct vnode *rvp" "struct lwp *l" 61.Ft int 62.Fn vn_lock "struct vnode *vp" "int flags" 63.Ft void 64.Fn vn_markexec "struct vnode *vp" 65.Ft void 66.Fn vn_marktext "struct vnode *vp" 67.Ft int 68.Fn vn_open "struct nameidata *ndp" "int fmode" "int cmode" 69.Ft int 70.Fn vn_bdev_open "dev_t dev" "struct vnode **vpp" "struct lwp *l" 71.Ft int 72.Fn vn_bdev_openpath "struct pathbuf *pb" "struct vnode **vpp" "struct lwp *l" 73.Ft int 74.Fo vn_rdwr 75.Fa "enum uio_rw rw" "struct vnode *vp" "void *base" 76.Fa "int len" "off_t offset" "enum uio_seg segflg" "int ioflg" 77.Fa "kauth_cred_t cred" "size_t *aresid" "struct lwp *l" 78.Fc 79.Ft int 80.Fn vn_readdir "file_t *fp" "char *buf" "int segflg" "u_int count" "int *done" "struct lwp *l" "off_t **cookies" "int *ncookies" 81.Ft int 82.Fn vn_stat "struct vnode *vp" "struct stat *sb" 83.Ft int 84.Fn vn_writechk "struct vnode *vp" 85.Sh DESCRIPTION 86The high-level functions described in this page are convenience 87functions for simplified access to the vnode operations described in 88.Xr vnodeops 9 . 89.Sh FUNCTIONS 90.Bl -tag -width compact 91.It Fn vn_bwrite "ap" 92Common code for block write operations. 93.It Fn vn_close "vp" "flags" "cred" 94Common code for a vnode close. 95The argument 96.Fa vp 97is the unlocked vnode of the vnode to close. 98.Fn vn_close 99simply locks the vnode, invokes the vnode operation 100.Xr VOP_CLOSE 9 101and calls 102.Fn vput 103to return the vnode to the freelist or holdlist. 104Note that 105.Fn vn_close 106expects an unlocked, referenced vnode and will dereference the vnode 107prior to returning. 108If the operation is successful zero is returned, 109otherwise an appropriate error is returned. 110.It Fn vn_default_error "v" 111A generic "default" routine that just returns error. 112It is used by a file system to specify unsupported operations in 113the vnode operations vector. 114.It Fn vn_isunder "dvp" "rvp" "l" 115Common code to check if one directory specified by the vnode 116.Fa rvp 117can be found inside the directory specified by the vnode 118.Fa dvp . 119The argument 120.Fa l 121is the calling process. 122.Fn vn_isunder 123is intended to be used in 124.Xr chroot 2 , 125.Xr chdir 2 , 126.Xr fchdir 2 , 127etc., to ensure that 128.Xr chroot 2 129actually means something. 130If the operation is successful zero is returned, otherwise 1 is returned. 131.It Fn vn_lock "vp" "flags" 132Common code to acquire the lock for vnode 133.Fa vp . 134The argument 135.Fa flags 136specifies the flags used to lock the vnode. 137There are the following flags: 138.Pp 139.Bl -tag -offset indent -width LK_EXCLUSIVE -compact 140.It LK_SHARED 141shared lock 142.It LK_EXCLUSIVE 143exclusive lock 144.It LK_NOWAIT 145do not sleep to await lock 146.It LK_RETRY 147allow lock operation on dead vnode 148.El 149.Pp 150If the operation is successful zero is returned, otherwise an 151appropriate error code is returned. 152.Pp 153.Fn vn_lock 154must not be called when the vnode's reference count is zero. 155.It Fn vn_markexec "vp" 156Common code to mark the vnode 157.Fa vp 158as containing executable code of a running process. 159.It Fn vn_marktext "vp" 160Common code to mark the vnode 161.Fa vp 162as being the text of a running process. 163.It Fn vn_open "ndp" "fmode" "cmode" 164Common code for vnode open operations. 165The pathname is described in the nameidata pointer (see 166.Xr namei 9 ) . 167The arguments 168.Fa fmode 169and 170.Fa cmode 171specify the 172.Xr open 2 173file mode and the access permissions for creation. 174.Fn vn_open 175checks permissions and invokes the 176.Xr VOP_OPEN 9 177or 178.Xr VOP_CREATE 9 179vnode operations. 180If the operation is successful zero is returned and the vnode is locked, 181otherwise an appropriate error code is returned. 182.It Fn vn_bdev_open "dev" "vpp" "l" 183Opens a block device by its device number for reading and writing, and 184stores the vnode pointer into 185.Fa *vpp . 186The argument 187.Fa l 188is the calling process. 189The vnode can be closed and freed with 190.Fa vn_close . 191.It Fn vn_bdev_openpath "pb" "vpp" "l" 192Works like 193.Fn vn_bdev_open 194but looks up a file system path 195.Fa pb 196to determine the device ID. 197.It Fn vn_rdwr "rw" "vp" "base" "len" "offset" "segflg" "ioflg" "cred" "aresid" "l" 198Common code to package up an I/O request on a vnode into a uio and 199then perform the I/O. 200The argument 201.Fa rw 202specifies whether the I/O is a read 203.Dv ( UIO_READ ) 204or write 205.Dv ( UIO_WRITE ) 206operation. 207The vnode is specified by 208.Fa vp . 209The arguments 210.Fa l 211and 212.Fa cred 213are the calling lwp and its credentials. 214If 215.Fa ioflg 216contains 217.Dv IO_NODELOCKED , 218it is expected that the vnode is locked. 219.Fa ioflg 220will be passed to 221.Fn VOP_READ Ns No / Ns Fn VOP_WRITE . 222The remaining arguments specify the uio parameters. 223For further information on these parameters see 224.Xr uiomove 9 . 225.It Fn vn_readdir "fp" "buf" "segflg" "count" "done" "l" "cookies" "ncookies" 226Common code for reading the contents of a directory. 227The argument 228.Fa fp 229is the file structure, 230.Fa buf 231is the buffer for placing the struct dirent structures. 232The arguments 233.Fa cookies 234and 235.Fa ncookies 236specify the addresses for the list and number of directory seek 237cookies generated for NFS. 238Both 239.Fa cookies 240and 241.Fa ncookies 242should be 243.Dv NULL 244if they aren't required to be returned by 245.Fn vn_readdir . 246If the operation is successful zero is returned, otherwise an 247appropriate error code is returned. 248.It Fn vn_stat "vp" "sb" 249Common code for a vnode stat operation. 250The vnode is specified by the argument 251.Fa vp , 252and 253.Fa sb 254is the buffer to return the stat information. 255.Fn vn_stat 256basically calls the vnode operation 257.Xr VOP_GETATTR 9 258and transfers the contents of a vattr structure into a struct stat. 259If the operation is successful zero is returned, otherwise an 260appropriate error code is returned. 261.It Fn vn_writechk "vp" 262Common code to check for write permission on the vnode 263.Fa vp . 264A vnode is read-only if it is in use as a process's text image. 265If the vnode is read-only ETEXTBSY is returned, otherwise zero is 266returned to indicate that the vnode can be written to. 267.El 268.Sh ERRORS 269.Bl -tag -width Er 270.It Bq Er EBUSY 271The LK_NOWAIT flag was set and 272.Fn vn_lock 273would have slept. 274.It Bq Er ENOENT 275The vnode has been reclaimed and is dead. 276This error is only returned if the LK_RETRY flag is not passed to 277.Fn vn_lock . 278.It Bq Er ETXTBSY 279Cannot write to a vnode since is a process's text image. 280.El 281.Sh CODE REFERENCES 282The high-level convenience functions are implemented within the files 283.Pa sys/kern/vfs_vnops.c 284and 285.Pa sys/sys/vnode.h . 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