1.\" $NetBSD: vfsops.9,v 1.46 2012/02/13 13:24:18 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 February 13, 2012 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" "struct quotactl_args *args" 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" "args" 284Query/modify user space quotas for the file system specified by the 285mount structure 286.Fa mp . 287The argument structure provides the operation ID and arguments to 288perform. 289This is the same interface as documented in 290.Xr __quotactl 2 291except that the file system argument has been resolved. 292All 293.Xr copyin 9 294and 295.Xr copyout 9 296processing is handled by code above the file system. 297.It Fn VFS_STATVFS "mp" "sbp" 298Get file system statistics for the file system specified by the mount 299structure 300.Fa mp . 301A statvfs structure filled with the statistics is returned in 302.Fa sbp . 303.Fn VFS_STATVFS 304is the file system type specific implementation of the 305.Xr statvfs 2 306and 307.Xr fstatvfs 2 308system calls. 309.It Fn VFS_SYNC "mp" "waitfor" "cred" 310Flush file system I/O buffers for the file system specified by the mount 311structure 312.Fa mp . 313The 314.Fa waitfor 315argument indicates whether a partial flush or complete flush should be 316performed. 317The argument 318.Fa cred 319specifies the calling credentials. 320.Fn VFS_SYNC 321does not provide any return value since the operation can never fail. 322.It Fn VFS_VGET "mp" "ino" "vpp" 323Get vnode for a file system type specific file id 324.Fa ino 325for the file system specified by the mount structure 326.Fa mp . 327The vnode is returned in the address specified 328.Fa vpp . 329The function is optional for file systems which have a unique id 330number for every file in the file system. 331It is used internally by the UFS file system and also by the NFSv3 332server to implement the READDIRPLUS NFS call. 333If the file system does not support this function, it should return 334.Er EOPNOTSUPP . 335.It Fn VFS_FHTOVP "mp" "fhp" "vpp" 336Get the vnode for the file handle 337.Fa fhp 338in the file system specified by the mount structure 339.Fa mp . 340The locked vnode is returned in 341.Fa vpp . 342.Pp 343When exporting, the call to 344.Fn VFS_FHTOVP 345should follow a call to 346.Fn netexport_check , 347which checks if the file is accessible to the client. 348.Pp 349If file handles are not supported by the file system, this function 350must return 351.Er EOPNOTSUPP . 352.It Fn VFS_VPTOFH "vp" "fhp" "fh_size" 353Get a file handle for the vnode specified by 354.Fa vp . 355The file handle is returned in 356.Fa fhp . 357The contents of the file handle are defined by the file system and are 358not examined by any other subsystems. 359It should contain enough information to uniquely identify a file within 360the file system as well as noticing when a file has been removed and 361the file system resources have been recycled for a new file. 362.Pp 363The parameter 364.Fa fh_size 365points to the container size for the file handle. 366This parameter should be updated to the size of the finished file handle. 367Note that it is legal to call this function with 368.Fa fhp 369set to 370.Dv NULL 371in case 372.Fa fh_size 373is zero. 374In case 375.Fa fh_size 376indicates a storage space too small, the storage space required for 377the file handle corresponding to 378.Fa vp 379should be filled in and 380.Er E2BIG 381should be returned. 382.Pp 383If file handles are not supported by the file system, this function 384must return 385.Er EOPNOTSUPP . 386.It Fn VFS_SNAPSHOT "mp" "vp" "ts" 387Take a snapshot of the file system specified by the mount structure 388.Fa mp 389and make it accessible through the locked vnode 390.Fa vp . 391If 392.Fa ts 393is not 394.Dv NULL 395it will receive the time this snapshot was taken. 396If the file system does not support this function, it should return 397.Er EOPNOTSUPP . 398.It Fn VFS_SUSPENDCTL "mp" "cmd" 399Suspend or resume all operations on this file system. 400.Fa cmd 401is either 402.Dv SUSPEND_SUSPEND 403to suspend or 404.Dv SUSPEND_RESUME 405to resume operations. 406If the file system does not support this function, it should return 407.Er EOPNOTSUPP . 408.El 409.Sh CODE REFERENCES 410The vfs operations are implemented within the files 411.Pa sys/kern/vfs_subr.c 412and 413.Pa sys/kern/vfs_init.c . 414.Sh SEE ALSO 415.Xr intro 9 , 416.Xr namei 9 , 417.Xr vfs 9 , 418.Xr vfssubr 9 , 419.Xr vnode 9 , 420.Xr vnodeops 9 421.Sh HISTORY 422The vfs operations vector, its functions and the corresponding macros 423appeared in 424.Bx 4.3 . 425