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