1.\" $NetBSD: vfsops.9,v 1.49 2019/01/01 10:06:54 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 January 1, 2019 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" "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" "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" "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 Initialze vnode with file 144.\" 145.It int (*vfs_loadvnode)() \ 146Ta Dv VFS_NEWVNODE \ 147Ta Initialze 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" "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 . 291This function is used by the pathname translation algorithms when a 292vnode that has been covered by a mounted file system is encountered. 293While resolving the pathname, the pathname translation algorithm will 294have to go through the directory tree in the file system associated 295with that mount point and therefore requires the root vnode of the 296file system. 297.It Fn VFS_QUOTACTL "mp" "args" 298Query/modify user space quotas for the file system specified by the 299mount structure 300.Fa mp . 301The argument structure provides the operation ID and arguments to 302perform. 303This is the same interface as documented in 304.Xr __quotactl 2 305except that the file system argument has been resolved. 306All 307.Xr copyin 9 308and 309.Xr copyout 9 310processing is handled by code above the file system. 311.It Fn VFS_STATVFS "mp" "sbp" 312Get file system statistics for the file system specified by the mount 313structure 314.Fa mp . 315A statvfs structure filled with the statistics is returned in 316.Fa sbp . 317.Fn VFS_STATVFS 318is the file system type specific implementation of the 319.Xr statvfs 2 320and 321.Xr fstatvfs 2 322system calls. 323.It Fn VFS_SYNC "mp" "waitfor" "cred" 324Flush file system I/O buffers for the file system specified by the mount 325structure 326.Fa mp . 327The 328.Fa waitfor 329argument indicates whether a partial flush or complete flush should be 330performed. 331The argument 332.Fa cred 333specifies the calling credentials. 334.Fn VFS_SYNC 335does not provide any return value since the operation can never fail. 336.It Fn VFS_VGET "mp" "ino" "vpp" 337Get vnode for a file system type specific file id 338.Fa ino 339for the file system specified by the mount structure 340.Fa mp . 341The vnode is returned in the address specified 342.Fa vpp . 343The function is optional for file systems which have a unique id 344number for every file in the file system. 345It is used internally by the UFS file system and also by the NFSv3 346server to implement the READDIRPLUS NFS call. 347If the file system does not support this function, it should return 348.Er EOPNOTSUPP . 349.It Fn VFS_LOADVNODE "mp" "vp" "key" "key_len" "new_key" 350Initialise the vnode 351.Fa vp 352with the file identified by the arguments 353.Fa key 354and 355.Fa key_len 356for the file system specified by the mount structure 357.Fa mp . 358.Pp 359The new key is returned in the address specified by 360.Fa new_key . 361.Pp 362Caller of this function assures no other thread will try to load this file. 363.It Fn VFS_NEWVNODE "mp" "dvp" "vp" "vap" "cred" "key_len" "new_key" 364Initialise the vnode 365.Fa vp 366with a new file for the file system specified by the mount structure 367.Fa mp . 368.Pp 369The argument 370.Fa dvp 371points to the directory to create the file in. 372.Pp 373The argument 374.Fa vap 375points to the attributes for the file to create. 376.Pp 377The argument 378.Fa cred 379holds the credentials for the file to create. 380.Pp 381The argument 382.Fa extra 383allows the caller to pass more information about the file to create. 384.Pp 385The key for the file is returned in the addresses specified by 386.Fa key_len 387and 388.Fa new_key . 389.It Fn VFS_FHTOVP "mp" "fhp" "vpp" 390Get the vnode for the file handle 391.Fa fhp 392in the file system specified by the mount structure 393.Fa mp . 394The locked vnode is returned in 395.Fa vpp . 396.Pp 397When exporting, the call to 398.Fn VFS_FHTOVP 399should follow a call to 400.Fn netexport_check , 401which checks if the file is accessible to the client. 402.Pp 403If file handles are not supported by the file system, this function 404must return 405.Er EOPNOTSUPP . 406.It Fn VFS_VPTOFH "vp" "fhp" "fh_size" 407Get a file handle for the vnode specified by 408.Fa vp . 409The file handle is returned in 410.Fa fhp . 411The contents of the file handle are defined by the file system and are 412not examined by any other subsystems. 413It should contain enough information to uniquely identify a file within 414the file system as well as noticing when a file has been removed and 415the file system resources have been recycled for a new file. 416.Pp 417The parameter 418.Fa fh_size 419points to the container size for the file handle. 420This parameter should be updated to the size of the finished file handle. 421Note that it is legal to call this function with 422.Fa fhp 423set to 424.Dv NULL 425in case 426.Fa fh_size 427is zero. 428In case 429.Fa fh_size 430indicates a storage space too small, the storage space required for 431the file handle corresponding to 432.Fa vp 433should be filled in and 434.Er E2BIG 435should be returned. 436.Pp 437If file handles are not supported by the file system, this function 438must return 439.Er EOPNOTSUPP . 440.It Fn VFS_SNAPSHOT "mp" "vp" "ts" 441Take a snapshot of the file system specified by the mount structure 442.Fa mp 443and make it accessible through the locked vnode 444.Fa vp . 445If 446.Fa ts 447is not 448.Dv NULL 449it will receive the time this snapshot was taken. 450If the file system does not support this function, it should return 451.Er EOPNOTSUPP . 452.It Fn VFS_SUSPENDCTL "mp" "cmd" 453Suspend or resume all operations on this file system. 454.Fa cmd 455is either 456.Dv SUSPEND_SUSPEND 457to suspend or 458.Dv SUSPEND_RESUME 459to resume operations. 460If the file system does not support this function, it should return 461.Er EOPNOTSUPP . 462.El 463.Sh CODE REFERENCES 464The vfs operations are implemented within the files 465.Pa sys/kern/vfs_subr.c 466and 467.Pa sys/kern/vfs_init.c . 468.Sh SEE ALSO 469.Xr intro 9 , 470.Xr namei 9 , 471.Xr vfs 9 , 472.Xr vfssubr 9 , 473.Xr vnode 9 , 474.Xr vnodeops 9 475.Sh HISTORY 476The vfs operations vector, its functions and the corresponding macros 477appeared in 478.Bx 4.3 . 479