1.\" $NetBSD: vnsubr.9,v 1.48 2021/06/29 22:40:53 dholland 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 June 28, 2021 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.Fo vn_open 69.Fa "struct vnode *at_dvp" "struct pathbuf *pb" 70.Fa "int nmode" "int fmode" "int cmode" 71.Fa "struct vnode **ret_vp" "bool *ret_domove" "int *ret_fd" 72.Fc 73.Ft int 74.Fn vn_bdev_open "dev_t dev" "struct vnode **vpp" "struct lwp *l" 75.Ft int 76.Fn vn_bdev_openpath "struct pathbuf *pb" "struct vnode **vpp" "struct lwp *l" 77.Ft int 78.Fo vn_rdwr 79.Fa "enum uio_rw rw" "struct vnode *vp" "void *base" 80.Fa "int len" "off_t offset" "enum uio_seg segflg" "int ioflg" 81.Fa "kauth_cred_t cred" "size_t *aresid" "struct lwp *l" 82.Fc 83.Ft int 84.Fn vn_readdir "file_t *fp" "char *buf" "int segflg" "u_int count" "int *done" "struct lwp *l" "off_t **cookies" "int *ncookies" 85.Ft int 86.Fn vn_stat "struct vnode *vp" "struct stat *sb" 87.Ft int 88.Fn vn_writechk "struct vnode *vp" 89.Sh DESCRIPTION 90The high-level functions described in this page are convenience 91functions for simplified access to the vnode operations described in 92.Xr vnodeops 9 . 93.Sh FUNCTIONS 94.Bl -tag -width compact 95.It Fn vn_bwrite "ap" 96Common code for block write operations. 97.It Fn vn_close "vp" "flags" "cred" 98Common code for a vnode close. 99The argument 100.Fa vp 101is the unlocked vnode of the vnode to close. 102.Fn vn_close 103simply locks the vnode, invokes the vnode operation 104.Xr VOP_CLOSE 9 105and calls 106.Fn vput 107to return the vnode to the freelist or holdlist. 108Note that 109.Fn vn_close 110expects an unlocked, referenced vnode and will dereference the vnode 111prior to returning. 112If the operation is successful zero is returned, 113otherwise an appropriate error is returned. 114.It Fn vn_default_error "v" 115A generic "default" routine that just returns error. 116It is used by a file system to specify unsupported operations in 117the vnode operations vector. 118.It Fn vn_isunder "dvp" "rvp" "l" 119Common code to check if one directory specified by the vnode 120.Fa rvp 121can be found inside the directory specified by the vnode 122.Fa dvp . 123The argument 124.Fa l 125is the calling process. 126.Fn vn_isunder 127is intended to be used in 128.Xr chroot 2 , 129.Xr chdir 2 , 130.Xr fchdir 2 , 131etc., to ensure that 132.Xr chroot 2 133actually means something. 134If the operation is successful zero is returned, otherwise 1 is returned. 135.It Fn vn_lock "vp" "flags" 136Common code to acquire the lock for vnode 137.Fa vp . 138The argument 139.Fa flags 140specifies the flags used to lock the vnode. 141There are the following flags: 142.Pp 143.Bl -tag -offset indent -width LK_EXCLUSIVE -compact 144.It LK_SHARED 145shared lock 146.It LK_EXCLUSIVE 147exclusive lock 148.It LK_NOWAIT 149do not sleep to await lock 150.It LK_RETRY 151allow lock operation on dead vnode 152.El 153.Pp 154If the operation is successful zero is returned, otherwise an 155appropriate error code is returned. 156.Pp 157.Fn vn_lock 158must not be called when the vnode's reference count is zero. 159.It Fn vn_markexec "vp" 160Common code to mark the vnode 161.Fa vp 162as containing executable code of a running process. 163.It Fn vn_marktext "vp" 164Common code to mark the vnode 165.Fa vp 166as being the text of a running process. 167.It Fn vn_open "at_dvp" "pb" "nmode" "fmode" "cmode" "ret_vp" "ret_domove" "ret_fd" 168Common code for vnode open operations. 169The 170.Fa at_dvp 171argument, if not NULL, provides the directory relative paths start 172from, as per 173.Xr openat 2 . 174The 175.Fa pb 176argument gives the pathname. 177The arguments 178.Fa nmode , 179.Fa fmode 180and 181.Fa cmode 182specify additional 183.Xr namei 9 184flags, the 185.Xr open 2 186flags (converted to 187.Dv F* 188from 189.Dv O_* 190form) 191and the access mode (permissions) for creation, respectively. 192The 193.Fa nmode 194argument is restricted to one or perhaps both of the flags 195.Dv TRYEMULROOT 196and 197.Dv NOCHROOT . 198Other 199.Xr name 9 200modes should be selected via 201.Fn fmode . 202The 203.Fa ret_vp , 204.Fa ret_domove , 205and 206.Fa ret_fd 207arguments encode the possible return values. 208When called, 209.Fn vn_open 210checks permissions and invokes the 211.Xr VOP_OPEN 9 212or 213.Xr VOP_CREATE 9 214vnode operations. 215If the operation is unsuccessful an appropriate error code is returned. 216Otherwise, zero is returned. 217If a vnode is produced, it is returned locked via 218.Fa ret_vp . 219If a file descriptor number is produced instead, the pointer passed via 220.Fa ret_vp 221is NULL, the file descriptor is returned via 222.Fa ret_fd , 223and the 224.Fa ret_domove 225returns a value that is true if the file descriptor should be moved 226rather than copied. 227These cases correspond to the internal errors 228.Dv EMOVEFD 229and 230.Dv EDUPFD 231respectively. 232See 233.Xr errno 9 234for further information. 235Callers unprepared to handle file descriptors can set 236.Fa ret_fd 237and 238.Fa ret_domove 239to NULL, in which case an operation that would produce a file descriptor 240will instead fail with 241.Dv EOPNOTSUPP . 242.It Fn vn_bdev_open "dev" "vpp" "l" 243Opens a block device by its device number for reading and writing, and 244stores the vnode pointer into 245.Fa *vpp . 246The argument 247.Fa l 248is the calling process. 249The vnode can be closed and freed with 250.Fa vn_close . 251.It Fn vn_bdev_openpath "pb" "vpp" "l" 252Works like 253.Fn vn_bdev_open 254but looks up a file system path 255.Fa pb 256to determine the device ID. 257.It Fn vn_rdwr "rw" "vp" "base" "len" "offset" "segflg" "ioflg" "cred" "aresid" "l" 258Common code to package up an I/O request on a vnode into a uio and 259then perform the I/O. 260The argument 261.Fa rw 262specifies whether the I/O is a read 263.Dv ( UIO_READ ) 264or write 265.Dv ( UIO_WRITE ) 266operation. 267The vnode is specified by 268.Fa vp . 269The arguments 270.Fa l 271and 272.Fa cred 273are the calling lwp and its credentials. 274If 275.Fa ioflg 276contains 277.Dv IO_NODELOCKED , 278it is expected that the vnode is locked. 279.Fa ioflg 280will be passed to 281.Fn VOP_READ Ns No / Ns Fn VOP_WRITE . 282The remaining arguments specify the uio parameters. 283For further information on these parameters see 284.Xr uiomove 9 . 285.It Fn vn_readdir "fp" "buf" "segflg" "count" "done" "l" "cookies" "ncookies" 286Common code for reading the contents of a directory. 287The argument 288.Fa fp 289is the file structure, 290.Fa buf 291is the buffer for placing the struct dirent structures. 292The arguments 293.Fa cookies 294and 295.Fa ncookies 296specify the addresses for the list and number of directory seek 297cookies generated for NFS. 298Both 299.Fa cookies 300and 301.Fa ncookies 302should be 303.Dv NULL 304if they aren't required to be returned by 305.Fn vn_readdir . 306If the operation is successful zero is returned, otherwise an 307appropriate error code is returned. 308.It Fn vn_stat "vp" "sb" 309Common code for a vnode stat operation. 310The vnode is specified by the argument 311.Fa vp , 312and 313.Fa sb 314is the buffer to return the stat information. 315.Fn vn_stat 316basically calls the vnode operation 317.Xr VOP_GETATTR 9 318and transfers the contents of a vattr structure into a struct stat. 319If the operation is successful zero is returned, otherwise an 320appropriate error code is returned. 321.It Fn vn_writechk "vp" 322Common code to check for write permission on the vnode 323.Fa vp . 324A vnode is read-only if it is in use as a process's text image. 325If the vnode is read-only ETEXTBSY is returned, otherwise zero is 326returned to indicate that the vnode can be written to. 327.El 328.Sh ERRORS 329.Bl -tag -width Er 330.It Bq Er EBUSY 331The LK_NOWAIT flag was set and 332.Fn vn_lock 333would have slept. 334.It Bq Er ENOENT 335The vnode has been reclaimed and is dead. 336This error is only returned if the LK_RETRY flag is not passed to 337.Fn vn_lock . 338.It Bq Er ETXTBSY 339Cannot write to a vnode since is a process's text image. 340.El 341.Sh CODE REFERENCES 342The high-level convenience functions are implemented within the files 343.Pa sys/kern/vfs_vnops.c 344and 345.Pa sys/sys/vnode.h . 346.Sh SEE ALSO 347.Xr file 9 , 348.Xr intro 9 , 349.Xr lock 9 , 350.Xr namei 9 , 351.Xr vattr 9 , 352.Xr vfs 9 , 353.Xr vnode 9 , 354.Xr vnodeops 9 355