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