1.\" $NetBSD: vnsubr.9,v 1.23 2005/12/20 19:53:15 rpaulo Exp $ 2.\" 3.\" Copyright (c) 2001 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd December 20, 2005 38.Dt VNSUBR 9 39.Os 40.Sh NAME 41.Nm vnsubr , 42.Nm vn_bwrite , 43.Nm vn_close , 44.Nm vn_default_error , 45.Nm vn_isunder , 46.Nm vn_lock , 47.Nm vn_markexec , 48.Nm vn_marktext , 49.Nm vn_rdwr , 50.Nm vn_restorerecurse , 51.Nm vn_setrecurse , 52.Nm vn_open , 53.Nm vn_stat , 54.Nm vn_writechk , 55.Nm vn_start_write , 56.Nm vn_finished_write , 57.Nm vn_cow_establish , 58.Nm vn_cow_disestablish 59.Nd high-level convenience functions for vnode operations 60.Sh SYNOPSIS 61.In sys/param.h 62.In sys/lock.h 63.In sys/vnode.h 64.Ft int 65.Fn vn_bwrite "void *ap" 66.Ft int 67.Fn vn_close "struct vnode *vp" "int flags" "struct ucred *cred" "struct lwp *l" 68.Ft int 69.Fn vn_default_error "void *v" 70.Ft int 71.Fn vn_isunder "struct vnode *dvp" "struct vnode *rvp" "struct lwp *l" 72.Ft int 73.Fn vn_lock "struct vnode *vp" "int flags" 74.Ft void 75.Fn vn_markexec "struct vnode *vp" 76.Ft void 77.Fn vn_marktext "struct vnode *vp" 78.Ft u_int 79.Fn vn_setrecurse "struct vnode *vp" 80.Ft void 81.Fn vn_restorerecurse "struct vnode *vp" "u_int flags" 82.Ft int 83.Fn vn_open "struct nameidata *ndp" "int fmode" "int cmode" 84.Ft int 85.Fo vn_rdwr 86.Fa "enum uio_rw rw" "struct vnode *vp" "caddr_t base" 87.Fa "int len" "off_t offset" "enum uio_seg segflg" "int ioflg" 88.Fa "struct ucred *cred" "size_t *aresid" "struct lwp *l" 89.Fc 90.Ft int 91.Fn vn_readdir "struct file *fp" "char *buf" "int segflg" "u_int count" "int *done" "struct lwp *l" "off_t **cookies" "int *ncookies" 92.Ft int 93.Fn vn_stat "struct vnode *vp" "struct stat *sb" "struct lwp *l" 94.Ft int 95.Fn vn_writechk "struct vnode *vp" 96.Ft int 97.Fn vn_start_write "struct vnode *vp" "struct mount **mpp" "int flags" 98.Ft void 99.Fn vn_finished_write "struct mount *mp" "int flags" 100.Ft int 101.Fn vn_cow_establish "struct vnode *vp" "int (*func)(void *, struct buf *)" "void *cookie" 102.Ft int 103.Fn vn_cow_disestablish "struct vnode *vp" "int (*func)(void *, struct buf *)" "void *cookie" 104.Sh DESCRIPTION 105The high-level functions described in this page are convenience 106functions for simplified access to the vnode operations described in 107.Xr vnodeops 9 . 108.Sh FUNCTIONS 109.Bl -tag -width compact 110.It Fn vn_bwrite "ap" 111Common code for block write operations. 112.It Fn vn_close "vp" "flags" "cred" "p" 113Common code for a vnode close. 114The argument 115.Fa vp 116is the unlocked vnode of the vnode to close. 117.Fn vn_close 118simply locks the vnode, invokes the vnode operation 119.Xr VOP_CLOSE 9 120and calls 121.Fn vput 122to return the vnode to the freelist or holdlist. 123Note that 124.Fn vn_close 125expects an unlocked, referenced vnode and will dereference the vnode 126prior to returning. 127If the operation is successful zero is returned, 128otherwise an appropriate error is returned. 129.It Fn vn_default_error "v" 130A generic "default" routine that just returns error. 131It is used by a file system to specify unsupported operations in 132the vnode operations vector. 133.It Fn vn_isunder "dvp" "rvp" "p" 134Common code to check if one directory specified by the vnode 135.Fa rvp 136can be found inside the directory specified by the vnode 137.Fa dvp . 138The argument 139.Fa p 140is the calling process. 141.Fn vn_isunder 142is intended to be used in 143.Xr chroot 2 , 144.Xr chdir 2 , 145.Xr fchdir 2 , 146etc., to ensure that 147.Xr chroot 2 148actually means something. 149If the operation is successful zero is returned, otherwise 1 is returned. 150.It Fn vn_lock "vp" "flags" 151Common code to acquire the lock for vnode 152.Fa vp . 153The argument 154.Fa flags 155specifies the 156.Xr lockmgr 9 157flags used to lock the vnode. 158If the operation is successful zero is returned, otherwise an 159appropriate error code is returned. 160The vnode interlock 161.Em v_interlock 162is releases on return. 163.Pp 164.Fn vn_lock 165must not be called when the vnode's reference count is zero. 166Instead, 167.Xr vget 9 168should be used. 169.It Fn vn_markexec "vp" 170Common code to mark the vnode 171.Fa vp 172as containing executable code of a running process. 173.It Fn vn_marktext "vp" 174Common code to mark the vnode 175.Fa vp 176as being the text of a running process. 177.It Fn vn_setrecurse "vp" 178Common code to enable LK_CANRECURSE on the vnode lock for vnode 179.Fa vp . 180.Fn vn_setrecurse 181returns the new 182.Xr lockmgr 9 183flags after the update. 184.It Fn vn_restorerecurse "vp" "flags" 185Common code to restore the vnode lock flags for the vnode 186.Fa vp . 187It is called when done with 188.Fn vn_setrecurse . 189.It Fn vn_open "ndp" "fmode" "cmode" 190Common code for vnode open operations. 191The pathname is described in the nameidata pointer (see 192.Xr namei 9 ) . 193The arguments 194.Fa fmode 195and 196.Fa cmode 197specify the 198.Xr open 2 199file mode and the access permissions for creation. 200.Fn vn_open 201checks permissions and invokes the 202.Xr VOP_OPEN 9 203or 204.Xr VOP_CREATE 9 205vnode operations. 206If the operation is successful zero is returned, 207otherwise an appropriate error code is returned. 208.It Fn vn_rdwr "rw" "vp" "base" "len" "offset" "segflg" "ioflg" "cred" "aresid" "p" 209Common code to package up an I/O request on a vnode into a uio and 210then perform the I/O. 211The argument 212.Fa rw 213specifies whether the I/O is a read (UIO_READ) or write (UIO_WRITE) 214operation. 215The unlocked vnode is specified by 216.Fa vp . 217The arguments 218.Fa p 219and 220.Fa cred 221are the calling process and its credentials. 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" "p" "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 NULL is they aren't required to be returned by 243.Fn vn_readdir . 244If the operation is successful zero is returned, otherwise an 245appropriate error code is returned. 246.It Fn vn_stat "vp" "sb" "p" 247Common code for a vnode stat operation. 248The vnode is specified by the argument 249.Fa vp , 250and 251.Fa sb 252is the buffer to return the stat information. 253The argument 254.Fa p 255is the calling process. 256.Fn vn_stat 257basically calls the vnode operation 258.Xr VOP_GETATTR 9 259and transfers the contents of a vattr structure into a struct stat. 260If the operation is successful zero is returned, otherwise an 261appropriate error code is returned. 262.It Fn vn_writechk "vp" 263Common code to check for write permission on the vnode 264.Fa vp . 265A vnode is read-only if it is in use as a process's text image. 266If the vnode is read-only ETEXTBSY is returned, otherwise zero is 267returned to indicate that the vnode can be written to. 268.It Fn vn_start_write "vp" "mpp" "flags" 269Prepare to start a file system write operation. 270If the operation is permitted, bump the count of operations in progress and 271proceed. 272If a suspend request is in progress (see 273.Xr vfs_write_suspend 9 ) , 274wait until the suspension is over 275and proceed. 276If 277.Fa vp 278is not 279.Dv NULL , 280its mount point is assigned to 281.Fa mpp . 282If the 283.Dv V_WAIT 284flag is set, 285.Fn vn_start_write 286waits until the suspension is over. 287Otherwise it returns 288.Er EWOULDBLOCK . 289If the 290.Dv V_PCATCH 291flag is set, 292.Dv PCATCH 293gets added to the 294.Fn tsleep 295flags. 296If the 297.Dv V_SLEEPONLY 298flag is set, the operations count is not bumped. 299If the 300.Dv V_LOWER 301flag is set, no further vnodes must be locked. 302If it is not set, no vnodes must be already locked. 303If the operation is permitted zero is returned, otherwise 304.Er EWOULDBLOCK 305is returned. 306.It Fn vn_finished_write "mp" "flags" 307A file system write operation has finished. 308Adjust the count of operations in progress and return. 309Only the 310.Dv V_LOWER 311flag is valid. 312.It Fn vn_cow_establish "vp" "func" "cookie" 313Establish a copy-on-write callback on spec vnode 314.Fa vp . 315.Fa func 316will be called for every buffer written through the strategy routine of 317.Fa vp . 318.It Fn vn_cow_disestablish "vp" "func" "cookie" 319Disestablish a copy-on-write callback registered with 320.Fn vn_cow_establish . 321.El 322.Sh ERRORS 323.Bl -tag -width Er 324.It Bq Er ETXTBSY 325Cannot write to a vnode since is a process's text image. 326.It Bq Er ENOENT 327The vnode has been reclaimed and is dead. 328This error is only returned if the LK_RETRY flag is not passed to 329.Fn vn_lock . 330.It Bq Er EBUSY 331The LK_NOWAIT flag was set and 332.Fn vn_lock 333would have slept. 334.El 335.Sh CODE REFERENCES 336This section describes places within the 337.Nx 338source tree where actual code implementing or using the vnode 339framework can be found. 340All pathnames are relative to 341.Pa /usr/src . 342.Pp 343The high-level convenience functions are implemented within the files 344.Pa sys/kern/vfs_vnops.c 345and 346.Pa sys/sys/vnode.h . 347.Sh SEE ALSO 348.Xr file 9 , 349.Xr intro 9 , 350.Xr lock 9 , 351.Xr namei 9 , 352.Xr vattr 9 , 353.Xr vfs 9 , 354.Xr vnode 9 , 355.Xr vnodeops 9 356