1.\" $NetBSD: vfsops.9,v 1.53 2020/08/28 07:28:59 hannken 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.\" 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 August 7, 2020 31.Dt VFSOPS 9 32.Os 33.Sh NAME 34.Nm vfsops , 35.Nm VFS_MOUNT , 36.Nm VFS_START , 37.Nm VFS_UNMOUNT , 38.Nm VFS_ROOT , 39.Nm VFS_QUOTACTL , 40.Nm VFS_STATVFS , 41.Nm VFS_SYNC , 42.Nm VFS_VGET , 43.Nm VFS_LOADVNODE , 44.Nm VFS_NEWVNODE , 45.Nm VFS_FHTOVP , 46.Nm VFS_VPTOFH , 47.Nm VFS_SNAPSHOT , 48.Nm VFS_SUSPENDCTL 49.Nd kernel file system interface 50.Sh SYNOPSIS 51.In sys/param.h 52.In sys/mount.h 53.In sys/vnode.h 54.Ft int 55.Fo VFS_MOUNT 56.Fa "struct mount *mp" "const char *path" "void *data" "size_t *dlen" 57.Fc 58.Ft int 59.Fn VFS_START "struct mount *mp" "int flags" 60.Ft int 61.Fn VFS_UNMOUNT "struct mount *mp" "int mntflags" 62.Ft int 63.Fn VFS_ROOT "struct mount *mp" "int lktype" "struct vnode **vpp" 64.Ft int 65.Fn VFS_QUOTACTL "struct mount *mp" "struct quotactl_args *args" 66.Ft int 67.Fn VFS_STATVFS "struct mount *mp" "struct statvfs *sbp" 68.Ft int 69.Fn VFS_SYNC "struct mount *mp" "int waitfor" "kauth_cred_t cred" 70.Ft int 71.Fn VFS_VGET "struct mount *mp" "ino_t ino" "int lktype" "struct vnode **vpp" 72.Ft int 73.Fn VFS_LOADVNODE "struct mount *mp" "struct vnode *vp" "const void *key" "size_t key_len" "const void **new_key" 74.Ft int 75.Fn VFS_NEWVNODE "struct mount *mp" "struct vnode *dvp" "struct vnode *vp" "struct vattr *vap" "kauth_cred_t cred" "void *extra" "size_t *key_len" "const void **new_key" 76.Ft int 77.Fn VFS_FHTOVP "struct mount *mp" "struct fid *fhp" "int lktype" "struct vnode **vpp" 78.Ft int 79.Fn VFS_VPTOFH "struct vnode *vp" "struct fid *fhp" "size_t *fh_size" 80.Ft int 81.Fn VFS_SNAPSHOT "struct mount *mp" "struct vnode *vp" "struct timespec *ts" 82.Ft int 83.Fn VFS_SUSPENDCTL "struct mount *mp" "int cmd" 84.Sh DESCRIPTION 85In a similar fashion to the 86.Xr vnode 9 87interface, all operations that are done on a file system are conducted 88through a single interface that allows the system to carry out 89operations on a file system without knowing its construction or type. 90.Pp 91All supported file systems in the kernel have an entry in the 92.Va vfs_list_initial 93table. 94This table is generated by 95.Xr config 1 96and is a 97.Dv NULL Ns No -terminated 98list of 99.Vt vfsops 100structures. 101The vfsops structure describes the operations that can be done to a 102specific file system type. 103The following table lists the elements of the vfsops vector, the 104corresponding invocation macro, and a description of the element. 105.Pp 106.Bl -column "int (*vfs_suspendctl)()" "VFS_SUSPENDCTL" -compact 107.It Sy Vector element Ta Sy Macro Ta Sy Description 108.\" 109.It int (*vfs_mount)() \ 110Ta Dv VFS_MOUNT \ 111Ta Mount a file system 112.\" 113.It int (*vfs_start)() \ 114Ta Dv VFS_START \ 115Ta Make operational 116.\" 117.It int (*vfs_unmount)() \ 118Ta Dv VFS_UNMOUNT \ 119Ta Unmount a file system 120.\" 121.It int (*vfs_root)() \ 122Ta Dv VFS_ROOT \ 123Ta Get the file system root vnode 124.\" 125.It int (*vfs_quotactl)() \ 126Ta Dv VFS_QUOTACTL \ 127Ta Query/modify space quotas 128.\" 129.It int (*vfs_statvfs)() \ 130Ta Dv VFS_STATVFS \ 131Ta Get file system statistics 132.\" 133.It int (*vfs_sync)() \ 134Ta Dv VFS_SYNC \ 135Ta Flush file system buffers 136.\" 137.It int (*vfs_vget)() \ 138Ta Dv VFS_VGET \ 139Ta Get vnode from file id 140.\" 141.It int (*vfs_loadvnode)() \ 142Ta Dv VFS_LOADVNODE \ 143Ta Initialize vnode with file 144.\" 145.It int (*vfs_newvnode)() \ 146Ta Dv VFS_NEWVNODE \ 147Ta Initialize vnode with new file 148.\" 149.It int (*vfs_fhtovp)() \ 150Ta Dv VFS_FHTOVP \ 151Ta NFS file handle to vnode lookup 152.\" 153.It int (*vfs_vptofh)() \ 154Ta Dv VFS_VPTOFH \ 155Ta Vnode to NFS file handle lookup 156.\" 157.It void (*vfs_init)() \ 158Ta \- \ 159Ta Initialize file system 160.\" 161.It void (*vfs_reinit)() \ 162Ta \- \ 163Ta Reinitialize file system 164.\" 165.It void (*vfs_done)() \ 166Ta \- \ 167Ta Cleanup unmounted file system 168.\" 169.It int (*vfs_mountroot)() \ 170Ta \- \ 171Ta Mount the root file system 172.\" 173.It int (*vfs_snapshot)() \ 174Ta Dv VFS_SNAPSHOT \ 175Ta Take a snapshot 176.\" 177.It int (*vfs_suspendctl)() \ 178Ta Dv VFS_SUSPENDCTL \ 179Ta Suspend or resume 180.El 181.Pp 182Some additional non-function members of the vfsops structure are the 183file system name 184.Fa vfs_name 185and a reference count 186.Fa vfs_refcount . 187It is not mandatory for a file system type to support a particular 188operation, but it must assign each member function pointer to a 189suitable function to do the minimum required of it. 190In most cases, such functions either do nothing or return an error 191value to the effect that it is not supported. 192.Fa vfs_reinit , 193.Fa vfs_mountroot , 194.Fa vfs_fhtovp , 195and 196.Fa vfs_vptofh 197may 198be 199.Dv NULL . 200.Pp 201At system boot, each file system with an entry in 202.Va vfs_list_initial 203is established and initialized. 204Each initialized file system is recorded by the kernel in the list 205.Va vfs_list 206and the file system specific initialization function 207.Fa vfs_init 208in its vfsops vector is invoked. 209When the file system is no longer needed 210.Fa vfs_done 211is invoked to run file system specific cleanups and the file system is 212removed from the kernel list. 213.Pp 214At system boot, the root file system is mounted by invoking the file 215system type specific 216.Fa vfs_mountroot 217function in the vfsops vector. 218All file systems that can be mounted as a root file system must define 219this function. 220It is responsible for initializing to list of mount structures for 221all future mounted file systems. 222.Pp 223Kernel state which affects a specific file system type can be 224queried and modified using the 225.Xr sysctl 8 226interface. 227.Sh FUNCTIONS 228.Bl -tag -width compact 229.It Fn VFS_MOUNT "mp" "path" "data" "dlen" 230Mount a file system specified by the mount structure 231.Fa mp 232on the mount point described by 233.Fa path . 234The argument 235.Fa data 236contains file system type specific data, while the argument 237.Fa dlen 238points to a location specifying the length of the data. 239.Pp 240.Fn VFS_MOUNT 241initializes the mount structure for the mounted file system. 242This structure records mount-specific information for the file system and 243records the list of vnodes associated with the file system. 244This function is invoked both to mount new file systems and to change the 245attributes of an existing file system. 246If the flag 247.Dv MNT_UPDATE 248is set in 249.Va mp->mnt_flag , 250the file system should update its state. 251This can be used, for instance, to convert a read-only file system to 252read-write. 253The current attributes for a mounted file system can be fetched by 254specifying 255.Dv MNT_GETARGS . 256If neither 257.Dv MNT_UPDATE 258or 259.Dv MNT_GETARGS 260are specified, a new file system will attempted to be mounted. 261.It Fn VFS_START "mp" "flags" 262Make the file system specified by the mount structure 263.Fa mp 264operational. 265The argument 266.Fa flags 267is a set of flags for controlling the operation of 268.Fn VFS_START . 269This function is invoked after 270.Fn VFS_MOUNT 271and before the first access to the file system. 272.It Fn VFS_UNMOUNT "mp" "mntflags" 273Unmount a file system specified by the mount structure 274.Fa mp . 275.Fn VFS_UNMOUNT 276performs any file system type specific operations required before the 277file system is unmounted, such are flushing buffers. 278If 279.Dv MNT_FORCE 280is specified in the flags 281.Fa mntflags 282then open files are forcibly closed. 283The function also deallocates space associated with data structure 284that were allocated for the file system when it was mounted. 285.It Fn VFS_ROOT "mp" "lktype" "vpp" 286Get the root vnode of the file system specified by the mount 287structure 288.Fa mp . 289The vnode is returned in the address given by 290.Fa vpp , 291with lock type 292.Fa lktype . 293.Fa lktype 294can be 295.Dv LK_NONE , 296or 297.Dv LK_SHARED , 298or 299.Dv LK_EXCLUSIVE . 300This function is used by the pathname translation algorithms when a 301vnode that has been covered by a mounted file system is encountered. 302While resolving the pathname, the pathname translation algorithm will 303have to go through the directory tree in the file system associated 304with that mount point and therefore requires the root vnode of the 305file system. 306.It Fn VFS_QUOTACTL "mp" "args" 307Query/modify user space quotas for the file system specified by the 308mount structure 309.Fa mp . 310The argument structure provides the operation ID and arguments to 311perform. 312This is the same interface as documented in 313.Xr __quotactl 2 314except that the file system argument has been resolved. 315All 316.Xr copyin 9 317and 318.Xr copyout 9 319processing is handled by code above the file system. 320.It Fn VFS_STATVFS "mp" "sbp" 321Get file system statistics for the file system specified by the mount 322structure 323.Fa mp . 324A statvfs structure filled with the statistics is returned in 325.Fa sbp . 326.Fn VFS_STATVFS 327is the file system type specific implementation of the 328.Xr statvfs 2 329and 330.Xr fstatvfs 2 331system calls. 332.It Fn VFS_SYNC "mp" "waitfor" "cred" 333Flush file system I/O buffers for the file system specified by the mount 334structure 335.Fa mp . 336The 337.Fa waitfor 338argument indicates whether a partial flush or complete flush should be 339performed. 340The argument 341.Fa cred 342specifies the calling credentials. 343.Fn VFS_SYNC 344does not provide any return value since the operation can never fail. 345.It Fn VFS_VGET "mp" "ino" "lktype" "vpp" 346Get vnode for a file system type specific file id 347.Fa ino 348for the file system specified by the mount structure 349.Fa mp , 350with lock type 351.Fa lktype . 352.Fa lktype 353can be 354.Dv LK_NONE , 355or 356.Dv LK_SHARED , 357or 358.Dv LK_EXCLUSIVE . 359The vnode is returned in the address specified 360.Fa vpp . 361The function is optional for file systems which have a unique id 362number for every file in the file system. 363It is used internally by the UFS file system and also by the NFSv3 364server to implement the READDIRPLUS NFS call. 365If the file system does not support this function, it should return 366.Er EOPNOTSUPP . 367.It Fn VFS_LOADVNODE "mp" "vp" "key" "key_len" "new_key" 368Initialise the vnode 369.Fa vp 370with the file identified by the arguments 371.Fa key 372and 373.Fa key_len 374for the file system specified by the mount structure 375.Fa mp . 376.Pp 377The new key is returned in the address specified by 378.Fa new_key . 379.Pp 380Caller of this function assures no other thread will try to load this file. 381.It Fn VFS_NEWVNODE "mp" "dvp" "vp" "vap" "cred" "extra" "key_len" "new_key" 382Initialise the vnode 383.Fa vp 384with a new file for the file system specified by the mount structure 385.Fa mp . 386.Pp 387The argument 388.Fa dvp 389points to the directory to create the file in. 390.Pp 391The argument 392.Fa vap 393points to the attributes for the file to create. 394.Pp 395The argument 396.Fa cred 397holds the credentials for the file to create. 398.Pp 399The argument 400.Fa extra 401allows the caller to pass more information about the file to create. 402.Pp 403The key for the file is returned in the addresses specified by 404.Fa key_len 405and 406.Fa new_key . 407.It Fn VFS_FHTOVP "mp" "fhp" "lktype" "vpp" 408Get the vnode for the file handle 409.Fa fhp 410in the file system specified by the mount structure 411.Fa mp , 412with lock type 413.Fa lktype . 414.Fa lktype 415can be 416.Dv LK_NONE , 417or 418.Dv LK_SHARED , 419or 420.Dv LK_EXCLUSIVE . 421The locked vnode is returned in 422.Fa vpp . 423.Pp 424When exporting, the call to 425.Fn VFS_FHTOVP 426should follow a call to 427.Fn netexport_check , 428which checks if the file is accessible to the client. 429.Pp 430If file handles are not supported by the file system, this function 431must return 432.Er EOPNOTSUPP . 433.It Fn VFS_VPTOFH "vp" "fhp" "fh_size" 434Get a file handle for the vnode specified by 435.Fa vp . 436The file handle is returned in 437.Fa fhp . 438The contents of the file handle are defined by the file system and are 439not examined by any other subsystems. 440It should contain enough information to uniquely identify a file within 441the file system as well as noticing when a file has been removed and 442the file system resources have been recycled for a new file. 443.Pp 444The parameter 445.Fa fh_size 446points to the container size for the file handle. 447This parameter should be updated to the size of the finished file handle. 448Note that it is legal to call this function with 449.Fa fhp 450set to 451.Dv NULL 452in case 453.Fa fh_size 454is zero. 455In case 456.Fa fh_size 457indicates a storage space too small, the storage space required for 458the file handle corresponding to 459.Fa vp 460should be filled in and 461.Er E2BIG 462should be returned. 463.Pp 464If file handles are not supported by the file system, this function 465must return 466.Er EOPNOTSUPP . 467.It Fn VFS_SNAPSHOT "mp" "vp" "ts" 468Take a snapshot of the file system specified by the mount structure 469.Fa mp 470and make it accessible through the locked vnode 471.Fa vp . 472If 473.Fa ts 474is not 475.Dv NULL 476it will receive the time this snapshot was taken. 477If the file system does not support this function, it should return 478.Er EOPNOTSUPP . 479.It Fn VFS_SUSPENDCTL "mp" "cmd" 480Suspend or resume all operations on this file system. 481.Fa cmd 482is either 483.Dv SUSPEND_SUSPEND 484to suspend or 485.Dv SUSPEND_RESUME 486to resume operations. 487If the file system does not support this function, it should return 488.Er EOPNOTSUPP . 489.El 490.Sh CODE REFERENCES 491The vfs operations are implemented within the files 492.Pa sys/kern/vfs_subr.c 493and 494.Pa sys/kern/vfs_init.c . 495.Sh SEE ALSO 496.Xr intro 9 , 497.Xr namei 9 , 498.Xr vfs 9 , 499.Xr vfssubr 9 , 500.Xr vnode 9 , 501.Xr vnodeops 9 502.Sh HISTORY 503The vfs operations vector, its functions and the corresponding macros 504appeared in 505.Bx 4.3 . 506