1.\" $NetBSD: vfsops.9,v 1.37 2008/12/23 09:11:59 stacktic 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 24, 2008 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.Em 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.nf 101.ta \w'int (*vfs_mountroot)()'u+2n +\w'VFS_QUOTACTL'u+2n +\w'Get the file system root vnode'u 102\fIVector element\fP \fIMacro\fP \fIDescription\fP 103.ta \w'int (*vfs_mountroot)()'u+2n +\w'VFS_QUOTACTL'u+2n +\w'Get the file system root vnode'u+6nC 104.sp 5p 105int (*vfs_mount)() VFS_MOUNT Mount a file system 106int (*vfs_start)() VFS_START Make operational 107int (*vfs_unmount)() VFS_UNMOUNT Unmount a file system 108int (*vfs_root)() VFS_ROOT Get the file system root vnode 109int (*vfs_quotactl)() VFS_QUOTACTL Query/modify space quotas 110int (*vfs_statvfs)() VFS_STATVFS Get file system statistics 111int (*vfs_sync)() VFS_SYNC Flush file system buffers 112int (*vfs_vget)() VFS_VGET Get vnode from file id 113int (*vfs_fhtovp)() VFS_FHTOVP NFS file handle to vnode lookup 114int (*vfs_vptofh)() VFS_VPTOFH Vnode to NFS file handle lookup 115void (*vfs_init)() - Initialize file system 116void (*vfs_reinit)() - Reinitialize file system 117void (*vfs_done)() - Cleanup unmounted file system 118int (*vfs_mountroot)() - Mount the root file system 119int (*vfs_snapshot)() VFS_SNAPSHOT Take a snapshot 120int (*vfs_suspendctl)() VFS_SUSPENDCTL Suspend or resume 121.fi 122.Pp 123Some additional non-function members of the vfsops structure are the 124file system name 125.Ns Em vfs_name 126and a reference count 127.Ns Em vfs_refcount . 128It is not mandatory for a file system type to support a particular 129operation, but it must assign each member function pointer to a 130suitable function to do the minimum required of it. 131In most cases, such functions either do nothing or return an error 132value to the effect that it is not supported. 133.Em vfs_reinit , 134.Em vfs_mountroot , 135.Em vfs_fhtovp , 136and 137.Em vfs_vptofh 138may 139be 140.Dv NULL . 141.Pp 142At system boot, each file system with an entry in 143.Va vfs_list_initial 144is established and initialized. 145Each initialized file system is recorded by the kernel in the list 146.Va vfs_list 147and the file system specific initialization function 148.Em vfs_init 149in its vfsops vector is invoked. 150When the file system is no longer needed 151.Em vfs_done 152is invoked to run file system specific cleanups and the file system is 153removed from the kernel list. 154.Pp 155At system boot, the root file system is mounted by invoking the file 156system type specific 157.Em vfs_mountroot 158function in the vfsops vector. 159All file systems that can be mounted as a root file system must define 160this function. 161It is responsible for initializing to list of mount structures for 162all future mounted file systems. 163.Pp 164Kernel state which affects a specific file system type can be 165queried and modified using the 166.Xr sysctl 8 167interface. 168.Sh FUNCTIONS 169.Bl -tag -width compact 170.It Fn VFS_MOUNT "mp" "path" "data" "dlen" 171Mount a file system specified by the mount structure 172.Fa mp 173on the mount point described by 174.Fa path . 175The argument 176.Fa data 177contains file system type specific data, while the argument 178.Fa dlen 179points to a location specifying the length of the data. 180.Pp 181.Fn VFS_MOUNT 182initializes the mount structure for the mounted file system. 183This structure records mount-specific information for the file system and 184records the list of vnodes associated with the file system. 185This function is invoked both to mount new file systems and to change the 186attributes of an existing file system. 187If the flag MNT_UPDATE is set in 188.Em mp-\*[Gt]mnt_flag , 189the file system should update its state. 190This can be used, for instance, to convert a read-only file system to 191read-write. 192The current attributes for a mounted file system can be fetched by 193specifying 194.Dv MNT_GETARGS . 195If neither 196.Dv MNT_UPDATE 197or 198.Dv MNT_GETARGS 199are specified, a new file system will attempted to be mounted. 200.It Fn VFS_START "mp" "flags" 201Make the file system specified by the mount structure 202.Fa mp 203operational. 204The argument 205.Fa flags 206is a set of flags for controlling the operation of 207.Fn VFS_START . 208This function is invoked after 209.Fn VFS_MOUNT 210and before the first access to the file system. 211.It Fn VFS_UNMOUNT "mp" "mntflags" 212Unmount a file system specified by the mount structure 213.Fa mp . 214.Fn VFS_UNMOUNT 215performs any file system type specific operations required before the 216file system is unmounted, such are flushing buffers. 217If MNT_FORCE is specified in the flags 218.Fa mntflags 219then open files are forcibly closed. 220The function also deallocates space associated with data structure 221that were allocated for the file system when it was mounted. 222.It Fn VFS_ROOT "mp" "vpp" 223Get the root vnode of the file system specified by the mount 224structure 225.Fa mp . 226The vnode is returned in the address given by 227.Fa vpp . 228This function is used by the pathname translation algorithms when a 229vnode that has been covered by a mounted file system is encountered. 230While resolving the pathname, the pathname translation algorithm will 231have to go through the directory tree in the file system associated 232with that mount point and therefore requires the root vnode of the 233file system. 234.It Fn VFS_QUOTACTL "mp" "cmds" "uid" "arg" 235Query/modify user space quotas for the file system specified by the 236mount structure 237.Fa mp . 238The argument specifies the control command to perform. 239The userid is specified in 240.Fa id 241and 242.Fa arg 243allows command-specific data to be returned to the system call 244interface. 245.Fn VFS_QUOTACTL 246is the file system type specific implementation of the 247.Xr quotactl 2 248system call. 249.It Fn VFS_STATVFS "mp" "sbp" 250Get file system statistics for the file system specified by the mount 251structure 252.Fa mp . 253A statvfs structure filled with the statistics is returned in 254.Fa sbp . 255.Fn VFS_STATVFS 256is the file system type specific implementation of the 257.Xr statvfs 2 258and 259.Xr fstatvfs 2 260system calls. 261.It Fn VFS_SYNC "mp" "waitfor" "cred" 262Flush file system I/O buffers for the file system specified by the mount 263structure 264.Fa mp . 265The 266.Fa waitfor 267argument indicates whether a partial flush or complete flush should be 268performed. 269The argument 270.Fa cred 271specifies the calling credentials. 272.Fn VFS_SYNC 273does not provide any return value since the operation can never fail. 274.It Fn VFS_VGET "mp" "ino" "vpp" 275Get vnode for a file system type specific file id 276.Fa ino 277for the file system specified by the mount structure 278.Fa mp . 279The vnode is returned in the address specified 280.Fa vpp . 281The function is optional for file systems which have a unique id 282number for every file in the file system. 283It is used internally by the UFS file system and also by the NFSv3 284server to implement the READDIRPLUS NFS call. 285If the file system does not support this function, it should return 286.Er EOPNOTSUPP . 287.It Fn VFS_FHTOVP "mp" "fhp" "vpp" 288Get the vnode for the file handle 289.Fa fhp 290in the file system specified by the mount structure 291.Fa mp . 292The locked vnode is returned in 293.Fa vpp . 294.Pp 295When exporting, the call to 296.Fn VFS_FHTOVP 297should follow a call to 298.Fn netexport_check , 299which checks if the file is accessible to the client. 300.Pp 301If file handles are not supported by the file system, this function 302must return 303.Er EOPNOTSUPP . 304.It Fn VFS_VPTOFH "vp" "fhp" "fh_size" 305Get a file handle for the vnode specified by 306.Fa vp . 307The file handle is returned in 308.Fa fhp . 309The contents of the file handle are defined by the file system and are 310not examined by any other subsystems. 311It should contain enough information to uniquely identify a file within 312the file system as well as noticing when a file has been removed and 313the file system resources have been recycled for a new file. 314.Pp 315The parameter 316.Fa fh_size 317points to the container size for the file handle. 318This parameter should be updated to the size of the finished file handle. 319Note that it is legal to call this function with 320.Fa fhp 321set to 322.Dv NULL 323in case 324.Fa fh_size 325is zero. 326In case 327.Fa fh_size 328indicates a storage space too small, the storage space required for 329the file handle corresponding to 330.Fa vp 331should be filled in and 332.Er E2BIG 333should be returned. 334.Pp 335If file handles are not supported by the file system, this function 336must return 337.Er EOPNOTSUPP . 338.It Fn VFS_SNAPSHOT "mp" "vp" "ts" 339Take a snapshot of the file system specified by the mount structure 340.Fa mp 341and make it accessible through the locked vnode 342.Fa vp . 343If 344.Fa ts 345is not 346.Dv NULL 347it will receive the time this snapshot was taken. 348If the file system does not support this function, it should return 349.Er EOPNOTSUPP . 350.It Fn VFS_SUSPENDCTL "mp" "cmd" 351Suspend or resume all operations on this file system. 352.Fa cmd 353is either 354.Dv SUSPEND_SUSPEND 355to suspend or 356.Dv SUSPEND_RESUME 357to resume operations. 358If the file system does not support this function, it should return 359.Er EOPNOTSUPP . 360.El 361.Sh CODE REFERENCES 362This section describes places within the 363.Nx 364source tree where actual code implementing or using the vfs 365operations can be found. 366All pathnames are relative to 367.Pa /usr/src . 368.Pp 369The vfs operations are implemented within the files 370.Pa sys/kern/vfs_subr.c , 371.Pa sys/kern/vfs_subr2.c 372and 373.Pa sys/kern/vfs_init.c . 374.Sh SEE ALSO 375.Xr intro 9 , 376.Xr namei 9 , 377.Xr vfs 9 , 378.Xr vfssubr 9 , 379.Xr vnode 9 , 380.Xr vnodeops 9 381.Sh HISTORY 382The vfs operations vector, its functions and the corresponding macros 383appeared in 384.Bx 4.3 . 385