1.\" $NetBSD: vnode.9,v 1.59 2014/02/22 11:28:18 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 February 22, 2014 31.Dt VNODE 9 32.Os 33.Sh NAME 34.Nm vnode , 35.Nm vref , 36.Nm vrele , 37.Nm vrele_async , 38.Nm vget , 39.Nm vput , 40.Nm vhold , 41.Nm holdrele , 42.Nm getnewvnode , 43.Nm ungetnewvnode , 44.Nm vrecycle , 45.Nm vgone , 46.Nm vgonel , 47.Nm vflush , 48.Nm vaccess , 49.Nm bdevvp , 50.Nm cdevvp , 51.Nm vfinddev , 52.Nm vdevgone , 53.Nm vwakeup , 54.Nm vflushbuf , 55.Nm vinvalbuf , 56.Nm vtruncbuf , 57.Nm vprint 58.Nd kernel representation of a file or directory 59.Sh SYNOPSIS 60.In sys/param.h 61.In sys/vnode.h 62.Ft void 63.Fn vref "struct vnode *vp" 64.Ft void 65.Fn vrele "struct vnode *vp" 66.Ft void 67.Fn vrele_async "struct vnode *vp" 68.Ft int 69.Fn vget "struct vnode *vp" "int lockflag" 70.Ft void 71.Fn vput "struct vnode *vp" 72.Ft void 73.Fn vhold "struct vnode *vp" 74.Ft void 75.Fn holdrele "struct vnode *vp" 76.Ft int 77.Fn getnewvnode "enum vtagtype tag" "struct mount *mp" "int (**vops)(void *)" \ 78"kmutex_t *slock" "struct vnode **vpp" 79.Ft void 80.Fn ungetnewvnode "struct vnode *vp" 81.Ft int 82.Fn vrecycle "struct vnode *vp" "struct kmutex_t *inter_lkp" 83.Ft void 84.Fn vgone "struct vnode *vp" 85.Ft void 86.Fn vgonel "struct vnode *vp" "struct lwp *l" 87.Ft int 88.Fn vflush "struct mount *mp" "struct vnode *skipvp" "int flags" 89.Ft int 90.Fn vaccess "enum vtype type" "mode_t file_mode" "uid_t uid" "gid_t gid" "mode_t acc_mode" "kauth_cred_t cred" 91.Ft int 92.Fn bdevvp "dev_t dev" "struct vnode **vpp" 93.Ft int 94.Fn cdevvp "dev_t dev" "struct vnode **vpp" 95.Ft int 96.Fn vfinddev "dev_t dev" "enum vtype" "struct vnode **vpp" 97.Ft void 98.Fn vdevgone "int maj" "int minl" "int minh" "enum vtype type" 99.Ft void 100.Fn vwakeup "struct buf *bp" 101.Ft int 102.Fn vflushbuf "struct vnode *vp" "int sync" 103.Ft int 104.Fn vinvalbuf "struct vnode *vp" "int flags" "kauth_cred_t cred" "struct lwp *l" "int slpflag" "int slptimeo" 105.Ft int 106.Fn vtruncbuf "struct vnode *vp" "daddr_t lbn" "int slpflag" "int slptimeo" 107.Ft void 108.Fn vprint "const char *label" "struct vnode *vp" 109.Sh DESCRIPTION 110The vnode is the focus of all file activity in 111.Nx . 112There is a unique vnode allocated for each active file, directory, 113mounted-on file, fifo, domain socket, symbolic link and device. 114The kernel has no concept of a file's underlying structure and so it 115relies on the information stored in the vnode to describe the file. 116Thus, the vnode associated with a file holds all the administration 117information pertaining to it. 118.Pp 119When a process requests an operation on a file, the 120.Xr vfs 9 121interface passes control to a file system type dependent function to carry 122out the operation. 123If the file system type dependent function finds that a vnode 124representing the file is not in main memory, it dynamically allocates 125a new vnode from the system main memory pool. 126Once allocated, the vnode is attached to the data structure pointer 127associated with the cause of the vnode allocation and it remains 128resident in the main memory until the system decides that it is no 129longer needed and can be recycled. 130.Pp 131The vnode has the following structure: 132.Bd -literal 133struct vnode { 134 struct uvm_object v_uobj; /* the VM object */ 135 kcondvar_t v_cv; /* synchronization */ 136 voff_t v_size; /* size of file */ 137 voff_t v_writesize; /* new size after write */ 138 int v_iflag; /* VI_* flags */ 139 int v_vflag; /* VV_* flags */ 140 int v_uflag; /* VU_* flags */ 141 int v_numoutput; /* # of pending writes */ 142 int v_writecount; /* ref count of writers */ 143 int v_holdcnt; /* page & buffer refs */ 144 int v_synclist_slot; /* synclist slot index */ 145 struct mount *v_mount; /* ptr to vfs we are in */ 146 int (**v_op)(void *); /* vnode operations vector */ 147 TAILQ_ENTRY(vnode) v_freelist; /* vnode freelist */ 148 struct vnodelst *v_freelisthd; /* which freelist? */ 149 TAILQ_ENTRY(vnode) v_mntvnodes; /* vnodes for mount point */ 150 struct buflists v_cleanblkhd; /* clean blocklist head */ 151 struct buflists v_dirtyblkhd; /* dirty blocklist head */ 152 TAILQ_ENTRY(vnode) v_synclist; /* vnodes with dirty bufs */ 153 LIST_HEAD(, namecache) v_dnclist; /* namecaches (children) */ 154 LIST_HEAD(, namecache) v_nclist; /* namecaches (parent) */ 155 union { 156 struct mount *vu_mountedhere;/* ptr to vfs (VDIR) */ 157 struct socket *vu_socket; /* unix ipc (VSOCK) */ 158 struct specnode *vu_specnode; /* device (VCHR, VBLK) */ 159 struct fifoinfo *vu_fifoinfo; /* fifo (VFIFO) */ 160 struct uvm_ractx *vu_ractx; /* read-ahead ctx (VREG) */ 161 } v_un; 162 enum vtype v_type; /* vnode type */ 163 enum vtagtype v_tag; /* type of underlying data */ 164 struct vnlock v_lock; /* lock for this vnode */ 165 void *v_data; /* private data for fs */ 166 struct klist v_klist; /* notes attached to vnode */ 167}; 168.Ed 169.Pp 170Most members of the vnode structure should be treated as opaque and 171only manipulated using the proper functions. 172There are some rather common exceptions detailed throughout this page. 173.Pp 174Files and file systems are inextricably linked with the virtual memory 175system and 176.Em v_uobj 177contains the data maintained by the virtual memory system. 178For compatibility with code written before the integration of 179.Xr uvm 9 180into 181.Nx , 182C-preprocessor directives are used to alias the members of 183.Em v_uobj . 184.Pp 185Vnode flags are recorded by 186.Em v_iflag , 187.Em v_vflag 188and 189.Em v_uflag . 190Valid flags are: 191.Pp 192.Bl -tag -offset indent -width ".Dv VI_WRMAPDIRTY" -compact 193.It Dv VV_ROOT 194This vnode is the root of its file system. 195.It Dv VV_SYSTEM 196This vnode is being used by the kernel; only used to skip quota files in 197.Fn vflush . 198.It Dv VV_ISTTY 199This vnode represents a tty; used when reading dead vnodes. 200.It Dv VV_MAPPED 201This vnode might have user mappings. 202.It Dv VV_MPSAFE 203This file system is MP safe. 204.It Dv VV_LOCKSWORK 205This vnode's file system supports locking. 206.It Dv VI_TEXT 207This vnode is a pure text prototype. 208.It Dv VI_EXECMAP 209This vnode has executable mappings. 210.It Dv VI_WRMAP 211This vnode might have PROT_WRITE user mappings. 212.It Dv VI_WRMAPDIRTY 213This vnode might have dirty pages due to 214.Dv VWRITEMAP . 215.It Dv VI_XLOCK 216This vnode is currently locked to change underlying type. 217.It Dv VI_ONWORKLST 218This vnode is on syncer work-list. 219.It Dv VI_MARKER 220A dummy marker vnode. 221.It Dv VI_LAYER 222This vnode is on a layered file system. 223.It Dv VI_LOCKSHARE 224This vnode shares its 225.Em v_interlock 226with other vnodes. 227.It Dv VI_CLEAN 228This vnode has been reclaimed and is no longer attached to a file system. 229.It Dv VU_DIROP 230This vnode is involved in a directory operation. 231This flag is used exclusively by LFS. 232.El 233.Pp 234The 235.Dv VI_XLOCK 236flag is used to prevent multiple processes from entering 237the vnode reclamation code. 238It is also used as a flag to indicate that reclamation is in progress. 239Before 240.Em v_iflag 241can be modified, the 242.Em v_interlock 243mutex must be acquired. 244See 245.Xr lock 9 246for details on the kernel locking API. 247.Pp 248Each vnode has three reference counts: 249.Em v_usecount , 250.Em v_writecount 251and 252.Em v_holdcnt . 253The first is the number of active references within the 254kernel to the vnode. 255This count is maintained by 256.Fn vref , 257.Fn vrele , 258.Fn vrele_async , 259and 260.Fn vput . 261The second is the number of active references within the kernel to the 262vnode performing write access to the file. 263It is maintained by the 264.Xr open 2 265and 266.Xr close 2 267system calls. 268The third is the number of references within the kernel 269requiring the vnode to remain active and not be recycled. 270This count is maintained by 271.Fn vhold 272and 273.Fn holdrele . 274When both the 275.Em v_usecount 276and 277.Em v_holdcnt 278reach zero, the vnode is recycled to the freelist and may be reused 279for another file. 280The transition to and from the freelist is handled by 281a kernel thread 282and 283.Fn vrecycle . 284Access to 285.Em v_usecount , 286.Em v_writecount 287and 288.Em v_holdcnt 289is also protected by the 290.Em v_interlock 291mutex. 292.Pp 293The number of pending synchronous and asynchronous writes on the 294vnode are recorded in 295.Em v_numoutput . 296It is used by 297.Xr fsync 2 298to wait for all writes to complete before returning to the user. 299Its value must only be modified at splbio (see 300.Xr spl 9 ) . 301It does not track the number of dirty buffers attached to the 302vnode. 303.Pp 304.Em v_dnclist 305and 306.Em v_nclist 307are used by 308.Xr namecache 9 309to maintain the list of associated entries so that 310.Xr cache_purge 9 311can purge them. 312.Pp 313The link to the file system which owns the vnode is recorded by 314.Em v_mount . 315See 316.Xr vfsops 9 317for further information of file system mount status. 318.Pp 319The 320.Em v_op 321pointer points to its vnode operations vector. 322This vector describes what operations can be done to the file associated 323with the vnode. 324The system maintains one vnode operations vector for each file system 325type configured into the kernel. 326The vnode operations vector contains a pointer to a function for 327each operation supported by the file system. 328See 329.Xr vnodeops 9 330for a description of vnode operations. 331.Pp 332When not in use, vnodes are kept on the freelist through 333.Em v_freelist . 334The vnodes still reference valid files but may be reused to refer to a 335new file at any time. 336When a valid vnode which is on the freelist is used again, the user 337must call 338.Fn vget 339to increment the reference count and retrieve it from the freelist. 340When a user wants a new vnode for another file, 341.Fn getnewvnode 342is invoked to allocate a vnode and initialize it for the new file. 343.Pp 344The type of object the vnode represents is recorded by 345.Em v_type . 346It is used by generic code to perform checks to ensure operations are 347performed on valid file system objects. 348Valid types are: 349.Pp 350.Bl -tag -offset indent -width VFIFO -compact 351.It Dv VNON 352The vnode has no type. 353.It Dv VREG 354The vnode represents a regular file. 355.It Dv VDIR 356The vnode represents a directory. 357.It Dv VBLK 358The vnode represents a block special device. 359.It Dv VCHR 360The vnode represents a character special device. 361.It Dv VLNK 362The vnode represents a symbolic link. 363.It Dv VSOCK 364The vnode represents a socket. 365.It Dv VFIFO 366The vnode represents a pipe. 367.It Dv VBAD 368The vnode represents a bad file (not currently used). 369.El 370.Pp 371Vnode tag types are used by external programs only (e.g., 372.Xr pstat 8 ) , 373and should never be inspected by the kernel. 374Its use is deprecated 375since new 376.Em v_tag 377values cannot be defined for loadable file systems. 378The 379.Em v_tag 380member is read-only. 381Valid tag types are: 382.Pp 383.Bl -tag -offset indent -width "VT_FILECORE " -compact 384.It Dv VT_NON 385non file system 386.It Dv VT_UFS 387universal file system 388.It Dv VT_NFS 389network file system 390.It Dv VT_MFS 391memory file system 392.It Dv VT_MSDOSFS 393FAT file system 394.It Dv VT_LFS 395log-structured file system 396.It Dv VT_LOFS 397loopback file system 398.It Dv VT_FDESC 399file descriptor file system 400.It Dv VT_NULL 401null file system layer 402.It Dv VT_UMAP 403uid/gid remapping file system layer 404.It Dv VT_KERNFS 405kernel interface file system 406.It Dv VT_PROCFS 407process interface file system 408.It Dv VT_AFS 409AFS file system 410.It Dv VT_ISOFS 411ISO 9660 file system(s) 412.It Dv VT_UNION 413union file system 414.It Dv VT_ADOSFS 415Amiga file system 416.It Dv VT_EXT2FS 417Linux's ext2 file system 418.It Dv VT_CODA 419Coda file system 420.It Dv VT_FILECORE 421filecore file system 422.It Dv VT_NTFS 423Microsoft NT's file system 424.It Dv VT_VFS 425virtual file system 426.It Dv VT_OVERLAY 427overlay file system 428.It Dv VT_SMBFS 429SMB file system 430.It Dv VT_PTYFS 431pseudo-terminal device file system 432.It Dv VT_TMPFS 433efficient memory file system 434.It Dv VT_UDF 435universal disk format file system 436.It Dv VT_SYSVBFS 437systemV boot file system 438.El 439.Pp 440All vnode locking operations use 441.Em v_lock . 442This lock is acquired by calling 443.Xr vn_lock 9 444and released by calling 445.Xr VOP_UNLOCK 9 . 446The reason for this asymmetry is that 447.Xr vn_lock 9 448is a wrapper for 449.Xr VOP_LOCK 9 450with extra checks, while the unlocking step usually does not need 451additional checks and thus has no wrapper. 452.Pp 453The vnode locking operation is complicated because it is used for many 454purposes. 455Sometimes it is used to bundle a series of vnode operations (see 456.Xr vnodeops 9 ) 457into an atomic group. 458Many file systems rely on it to prevent race conditions in updating 459file system type specific data structures rather than using their 460own private locks. 461The vnode lock can operate as a multiple-reader (shared-access lock) 462or single-writer lock (exclusive access lock), however many current file 463system implementations were written assuming only single-writer 464locking. 465Multiple-reader locking functions equivalently only in the presence 466of big-lock SMP locking or a uni-processor machine. 467The lock may be held while sleeping. 468While the 469.Em v_lock 470is acquired, the holder is guaranteed that the vnode will not be 471reclaimed or invalidated. 472Most file system functions require that you hold the vnode lock on entry. 473See 474.Xr lock 9 475for details on the kernel locking API. 476.Pp 477Each file system underlying a vnode allocates its own private area and 478hangs it from 479.Em v_data . 480.Pp 481Most functions discussed in this page that operate on vnodes cannot be 482called from interrupt context. 483The members 484.Em v_numoutput , 485.Em v_holdcnt , 486.Em v_dirtyblkhd , 487.Em v_cleanblkhd , 488.Em v_freelist , 489and 490.Em v_synclist 491are modified in interrupt context and must be protected by 492.Xr splbio 9 493unless it is certain that there is no chance an interrupt handler will 494modify them. 495The vnode lock must not be acquired within interrupt context. 496.Sh FUNCTIONS 497.Bl -tag -width compact 498.It Fn vref "vp" 499Increment 500.Em v_usecount 501of the vnode 502.Em vp . 503Any kernel thread system which uses a vnode (e.g., during the operation 504of some algorithm or to store in a data structure) should call 505.Fn vref . 506.It Fn vrele "vp" 507Decrement 508.Em v_usecount 509of unlocked vnode 510.Em vp . 511Any code in the system which is using a vnode should call 512.Fn vrele 513when it is finished with the vnode. 514If 515.Em v_usecount 516of the vnode reaches zero and 517.Em v_holdcnt 518is greater than zero, the vnode is placed on the holdlist. 519If both 520.Em v_usecount 521and 522.Em v_holdcnt 523are zero, the vnode is placed on the freelist. 524.It Fn vrele_async "vp" 525Will asychronously release the vnode in different context than the caller, 526sometime after the call. 527.It Fn vget "vp" "lockflags" 528Reclaim vnode 529.Fa vp 530from the freelist, increment its reference count and lock it. 531The argument 532.Fa lockflags 533specifies the 534.Xr rwlock 9 535flags used to lock the vnode. 536If the 537.Dv VI_XLOCK 538flag is set in 539.Fa vp Ns 's 540.Em v_flag , 541vnode 542.Fa vp 543is being recycled in 544.Fn vgone 545and the calling thread sleeps until the transition is complete. 546When it is awakened, an error is returned to indicate that the vnode is 547no longer usable. 548.It Fn vput "vp" 549Unlock vnode 550.Fa vp 551and decrement its 552.Em v_usecount . 553Depending on the reference counts, move the vnode to the holdlist or 554the freelist. 555This operation is functionally equivalent to calling 556.Xr VOP_UNLOCK 9 557followed by 558.Fn vrele . 559.It Fn vhold "vp" 560Mark the vnode 561.Fa vp 562as active by incrementing 563.Em vp-\*[Gt]v_holdcnt 564and moving the vnode from the freelist to the holdlist. 565Once on the holdlist, the vnode will not be recycled until it is 566released with 567.Fn holdrele . 568.It Fn holdrele "vp" 569Mark the vnode 570.Fa vp 571as inactive by decrementing 572.Em vp-\*[Gt]v_holdcnt 573and moving the vnode from the holdlist to the freelist. 574.It Fn getnewvnode "tag" "mp" "vops" "slock" "vpp" 575Retrieve the next vnode from the freelist. 576.Fn getnewvnode 577allocates a new vnode. 578The new vnode is returned in the address specified by 579.Fa vpp . 580.Pp 581The argument 582.Fa mp 583is the mount point for the file system requested the new vnode. 584Before retrieving the new vnode, the file system is checked if it is 585busy (such as currently unmounting). 586An error is returned if the file system is unmounted. 587.Pp 588The argument 589.Fa tag 590is the vnode tag assigned to 591.Fa *vpp-\*[Gt]v_tag . 592The argument 593.Fa vops 594is the vnode operations vector of the file system requesting the new 595vnode. 596If a vnode is successfully retrieved zero is returned, otherwise an 597appropriate error code is returned. 598If 599.Fa slock 600is not 601.Dv NULL , 602it specifies the lock to share for 603.Em v_interlock . 604The reference will be held on the lock and sharing noted. 605Reference will be released and lock unshared when the vnode gets recycled. 606If 607.Dv NULL 608(regular case), vnode will use its own interlock. 609.It Fn ungetnewvnode "vp" 610Undo the operation of 611.Fn getnewvnode . 612The argument 613.Fa vp 614is the vnode to return to the freelist. 615This function is needed for 616.Xr VFS_VGET 9 617which may need to push back a vnode in case of a locking race 618condition. 619.It Fn vrecycle "vp" "inter_lkp" 620Recycle the unused vnode 621.Fa vp 622from the front of the freelist. 623.Fn vrecycle 624is a null operation if the reference count is greater than zero. 625.It Fn vgone "vp" 626Eliminate all activity associated with the unlocked vnode 627.Fa vp 628in preparation for recycling. 629.It Fn vgonel "vp" "p" 630Eliminate all activity associated with the locked vnode 631.Fa vp 632in preparation for recycling. 633.It Fn vflush "mp" "skipvp" "flags" 634Remove any vnodes in the vnode table belonging to mount point 635.Fa mp . 636If 637.Fa skipvp 638is not 639.Dv NULL 640it is exempt from being flushed. 641The argument 642.Fa flags 643is a set of flags modifying the operation of 644.Fn vflush . 645If 646.Dv FORCECLOSE 647is not specified, there should not be any active vnodes and 648the error 649.Er EBUSY 650is returned if any are found (this is a user error, not a system error). 651If 652.Dv FORCECLOSE 653is specified, active vnodes that are found are detached. 654If 655.Dv WRITECLOSE 656is set, only flush out regular file vnodes open for writing. 657SKIPSYSTEM causes any vnodes marked 658.Dv V_SYSTEM 659to be skipped. 660.It Fn vaccess "type" "file_mode" "uid" "gid" "acc_mode" "cred" 661Do access checking by comparing the file's permissions to the caller's 662desired access type 663.Fa acc_mode 664and credentials 665.Fa cred . 666.It Fn bdevvp "dev" "vpp" 667Create a vnode for a block device. 668.Fn bdevvp 669is used for root file systems, swap areas and for memory file system 670special devices. 671.It Fn cdevvp "dev" "vpp" 672Create a vnode for a character device. 673.Fn cdevvp 674is used for the console and kernfs special devices. 675.It Fn vfinddev "dev" "vtype" "vpp" 676Lookup a vnode by device number. 677The vnode is referenced and returned in the address specified by 678.Fa vpp . 679.It Fn vdevgone "int maj" "int min" "int minh" "enum vtype type" 680Reclaim all vnodes that correspond to the specified minor number range 681.Fa minl 682to 683.Fa minh 684(endpoints inclusive) of the specified major 685.Fa maj . 686.It Fn vwakeup "bp" 687Update outstanding I/O count 688.Em vp-\*[Gt]v_numoutput 689for the vnode 690.Em bp-\*[Gt]b_vp 691and do a wakeup if requested and 692.Em vp-\*[Gt]vflag 693has 694.Dv VBWAIT 695set. 696.It Fn vflushbuf "vp" "sync" 697Flush all dirty buffers to disk for the file with the locked vnode 698.Fa vp . 699The argument 700.Fa sync 701specifies whether the I/O should be synchronous and 702.Fn vflushbuf 703will sleep until 704.Em vp-\*[Gt]v_numoutput 705is zero and 706.Em vp-\*[Gt]v_dirtyblkhd 707is empty. 708.It Fn vinvalbuf "vp" "flags" "cred" "l" "slpflag" "slptimeo" 709Flush out and invalidate all buffers associated with locked vnode 710.Fa vp . 711The argument 712.Fa l 713and 714.Fa cred 715specified the calling process and its credentials. 716The 717.Xr ltsleep 9 718flag and timeout are specified by the arguments 719.Fa slpflag 720and 721.Fa slptimeo 722respectively. 723If the operation is successful zero is returned, otherwise an 724appropriate error code is returned. 725.It Fn vtruncbuf "vp" "lbn" "slpflag" "slptimeo" 726Destroy any in-core buffers past the file truncation length for the 727locked vnode 728.Fa vp . 729The truncation length is specified by 730.Fa lbn . 731.Fn vtruncbuf 732will sleep while the I/O is performed, The 733.Xr ltsleep 9 734flag and timeout are specified by the arguments 735.Fa slpflag 736and 737.Fa slptimeo 738respectively. 739If the operation is successful zero is returned, otherwise an 740appropriate error code is returned. 741.It Fn vprint "label" "vp" 742This function is used by the kernel to dump vnode information during a 743panic. 744It is only used if the kernel option DIAGNOSTIC is compiled into the kernel. 745The argument 746.Fa label 747is a string to prefix the information dump of vnode 748.Fa vp . 749.El 750.Sh CODE REFERENCES 751The vnode framework is implemented within the file 752.Pa sys/kern/vfs_subr.c . 753.Sh SEE ALSO 754.Xr intro 9 , 755.Xr lock 9 , 756.Xr namecache 9 , 757.Xr namei 9 , 758.Xr uvm 9 , 759.Xr vattr 9 , 760.Xr vfs 9 , 761.Xr vfsops 9 , 762.Xr vnodeops 9 , 763.Xr vnsubr 9 764.Sh BUGS 765The locking protocol is inconsistent. 766Many vnode operations are passed locked vnodes on entry but release 767the lock before they exit. 768The locking protocol is used in some places to attempt to make a 769series of operations atomic (e.g., access check then operation). 770This does not work for non-local file systems that do not support locking 771(e.g., NFS). 772The 773.Nm 774interface would benefit from a simpler locking protocol. 775