1.\" $NetBSD: vfsops.9,v 1.48 2017/07/03 21:28:48 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.\" 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 July 12, 2015 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" "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 key for the file is returned in the addresses specified by 382.Fa key_len 383and 384.Fa new_key . 385.It Fn VFS_FHTOVP "mp" "fhp" "vpp" 386Get the vnode for the file handle 387.Fa fhp 388in the file system specified by the mount structure 389.Fa mp . 390The locked vnode is returned in 391.Fa vpp . 392.Pp 393When exporting, the call to 394.Fn VFS_FHTOVP 395should follow a call to 396.Fn netexport_check , 397which checks if the file is accessible to the client. 398.Pp 399If file handles are not supported by the file system, this function 400must return 401.Er EOPNOTSUPP . 402.It Fn VFS_VPTOFH "vp" "fhp" "fh_size" 403Get a file handle for the vnode specified by 404.Fa vp . 405The file handle is returned in 406.Fa fhp . 407The contents of the file handle are defined by the file system and are 408not examined by any other subsystems. 409It should contain enough information to uniquely identify a file within 410the file system as well as noticing when a file has been removed and 411the file system resources have been recycled for a new file. 412.Pp 413The parameter 414.Fa fh_size 415points to the container size for the file handle. 416This parameter should be updated to the size of the finished file handle. 417Note that it is legal to call this function with 418.Fa fhp 419set to 420.Dv NULL 421in case 422.Fa fh_size 423is zero. 424In case 425.Fa fh_size 426indicates a storage space too small, the storage space required for 427the file handle corresponding to 428.Fa vp 429should be filled in and 430.Er E2BIG 431should be returned. 432.Pp 433If file handles are not supported by the file system, this function 434must return 435.Er EOPNOTSUPP . 436.It Fn VFS_SNAPSHOT "mp" "vp" "ts" 437Take a snapshot of the file system specified by the mount structure 438.Fa mp 439and make it accessible through the locked vnode 440.Fa vp . 441If 442.Fa ts 443is not 444.Dv NULL 445it will receive the time this snapshot was taken. 446If the file system does not support this function, it should return 447.Er EOPNOTSUPP . 448.It Fn VFS_SUSPENDCTL "mp" "cmd" 449Suspend or resume all operations on this file system. 450.Fa cmd 451is either 452.Dv SUSPEND_SUSPEND 453to suspend or 454.Dv SUSPEND_RESUME 455to resume operations. 456If the file system does not support this function, it should return 457.Er EOPNOTSUPP . 458.El 459.Sh CODE REFERENCES 460The vfs operations are implemented within the files 461.Pa sys/kern/vfs_subr.c 462and 463.Pa sys/kern/vfs_init.c . 464.Sh SEE ALSO 465.Xr intro 9 , 466.Xr namei 9 , 467.Xr vfs 9 , 468.Xr vfssubr 9 , 469.Xr vnode 9 , 470.Xr vnodeops 9 471.Sh HISTORY 472The vfs operations vector, its functions and the corresponding macros 473appeared in 474.Bx 4.3 . 475