1.\" $NetBSD: vfsops.9,v 1.32 2007/07/31 21:39:56 pooka 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd July 31, 2007 38.Dt VFSOPS 9 39.Os 40.Sh NAME 41.Nm vfsops , 42.Nm VFS_MOUNT , 43.Nm VFS_START , 44.Nm VFS_UNMOUNT , 45.Nm VFS_ROOT , 46.Nm VFS_QUOTACTL , 47.Nm VFS_STATVFS , 48.Nm VFS_SYNC , 49.Nm VFS_VGET , 50.Nm VFS_FHTOVP , 51.Nm VFS_VPTOFH , 52.Nm VFS_SNAPSHOT , 53.Nm VFS_SUSPENDCTL 54.Nd kernel file system interface 55.Sh SYNOPSIS 56.In sys/param.h 57.In sys/mount.h 58.In sys/vnode.h 59.Ft int 60.Fo VFS_MOUNT 61.Fa "struct mount *mp" "const char *path" "void *data" "size_t *dlen" 62.Fa "struct lwp *l" 63.Fc 64.Ft int 65.Fn VFS_START "struct mount *mp" "int flags" "struct lwp *l" 66.Ft int 67.Fn VFS_UNMOUNT "struct mount *mp" "int mntflags" "struct lwp *l" 68.Ft int 69.Fn VFS_ROOT "struct mount *mp" "struct vnode **vpp" 70.Ft int 71.Fn VFS_QUOTACTL "struct mount *mp" "int cmds" "uid_t uid" \ 72"void *arg" "struct lwp *l" 73.Ft int 74.Fn VFS_STATVFS "struct mount *mp" "struct statvfs *sbp" "struct lwp *l" 75.Ft int 76.Fn VFS_SYNC "struct mount *mp" "int waitfor" "kauth_cred_t cred" \ 77"struct lwp *l" 78.Ft int 79.Fn VFS_VGET "struct mount *mp" "ino_t ino" "struct vnode **vpp" 80.Ft int 81.Fn VFS_FHTOVP "struct mount *mp" "struct fid *fhp" "struct vnode **vpp" 82.Ft int 83.Fn VFS_VPTOFH "struct vnode *vp" "struct fid *fhp" "size_t *fh_size" 84.Ft int 85.Fn VFS_SNAPSHOT "struct mount *mp" "struct vnode *vp" "struct timespec *ts" 86.Ft int 87.Fn VFS_SUSPENDCTL "struct mount *mp" "int cmd" 88.Sh DESCRIPTION 89In a similar fashion to the 90.Xr vnode 9 91interface, all operations that are done on a file system are conducted 92through a single interface that allows the system to carry out 93operations on a file system without knowing its construction or type. 94.Pp 95All supported file systems in the kernel have an entry in the 96.Va vfs_list_initial 97table. 98This table is generated by 99.Xr config 1 100and is a 101.Dv NULL Ns No -terminated 102list of 103.Em vfsops 104structures. 105The vfsops structure describes the operations that can be done to a 106specific file system type. 107The following table lists the elements of the vfsops vector, the 108corresponding invocation macro, and a description of the element. 109.Pp 110.nf 111.ta \w'int (*vfs_mountroot)()'u+2n +\w'VFS_QUOTACTL'u+2n +\w'Get the file system root vnode'u 112\fIVector element\fP \fIMacro\fP \fIDescription\fP 113.ta \w'int (*vfs_mountroot)()'u+2n +\w'VFS_QUOTACTL'u+2n +\w'Get the file system root vnode'u+6nC 114.sp 5p 115int (*vfs_mount)() VFS_MOUNT Mount a file system 116int (*vfs_start)() VFS_START Make operational 117int (*vfs_unmount)() VFS_UMOUNT Unmount a file system 118int (*vfs_root)() VFS_ROOT Get the file system root vnode 119int (*vfs_quotactl)() VFS_QUOTACTL Query/modify space quotas 120int (*vfs_statvfs)() VFS_STATVFS Get file system statistics 121int (*vfs_sync)() VFS_SYNC Flush file system buffers 122int (*vfs_vget)() VFS_VGET Get vnode from file id 123int (*vfs_fhtovp)() VFS_FHTOVP NFS file handle to vnode lookup 124int (*vfs_vptofh)() VFS_VPTOFH Vnode to NFS file handle lookup 125void (*vfs_init)() - Initialise file system 126void (*vfs_reinit)() - Reinitialise file system 127void (*vfs_done)() - Cleanup unmounted file system 128int (*vfs_mountroot)() - Mount the root file system 129int (*vfs_snapshot)() VFS_SNAPSHOT Take a snapshot 130int (*vfs_suspendctl)() VFS_SUSPENDCTL Suspend or resume 131.fi 132.Pp 133Some additional non-function members of the vfsops structure are the 134file system name 135.Ns Em vfs_name 136and a reference count 137.Ns Em vfs_refcount . 138It is not mandatory for a file system type to support a particular 139operation, but it must assign each member function pointer to a 140suitable function to do the minimum required of it. 141In most cases, such functions either do nothing or return an error 142value to the effect that it is not supported. 143.Em vfs_reinit , 144.Em vfs_mountroot , 145.Em vfs_fhtovp , 146and 147.Em vfs_vptofh 148may 149be 150.Dv NULL . 151.Pp 152At system boot, each file system with an entry in 153.Va vfs_list_initial 154is established and initialised. 155Each initialised file system is recorded by the kernel in the list 156.Va vfs_list 157and the file system specific initialisation function 158.Em vfs_init 159in its vfsops vector is invoked. 160When the file system is no longer needed 161.Em vfs_done 162is invoked to run file system specific cleanups and the file system is 163removed from the kernel list. 164.Pp 165At system boot, the root filesystem is mounted by invoking the file 166system type specific 167.Em vfs_mountroot 168function in the vfsops vector. 169All filesystems that can be mounted as a root file system must define 170this function. 171It is responsible for initialising to list of mount structures for 172all future mounted file systems. 173.Pp 174Kernel state which affects a specific file system type can be 175queried and modified using the 176.Xr sysctl 8 177interface. 178.Sh FUNCTIONS 179.Bl -tag -width compact 180.It Fn VFS_MOUNT "mp" "path" "data" "dlen" "l" 181Mount a file system specified by the mount structure 182.Fa mp 183on the mount point described by 184.Fa path . 185The argument 186.Fa data 187contains file system type specific data, while the argument 188.Fa dlen 189points to a location specifying the length of the data. 190The argument 191.Fa l 192is the calling lwp. 193.Pp 194.Fn VFS_MOUNT 195initialises the mount structure for the mounted file system. 196This structure records mount-specific information for the file system and 197records the list of vnodes associated with the file system. 198This function is invoked both to mount new file systems and to change the 199attributes of an existing file system. 200If the flag MNT_UPDATE is set in 201.Em mp-\*[Gt]mnt_flag , 202the filesystem should update its state. 203This can be used, for instance, to convert a read-only filesystem to 204read-write. 205The current attributes for a mounted file system can be fetched by 206specifying 207.Dv MNT_GETARGS . 208If neither 209.Dv MNT_UPDATE 210or 211.Dv MNT_GETARGS 212are specified, a new file system will attempted to be mounted. 213.It Fn VFS_START "mp" "flags" "l" 214Make the file system specified by the mount structure 215.Fa mp 216operational. 217The argument 218.Fa l 219is the calling lwp. 220The argument 221.Fa flags 222is a set of flags for controlling the operation of 223.Fn VFS_START . 224This function is invoked after 225.Fn VFS_MOUNT 226and before the first access to the file system. 227.It Fn VFS_UNMOUNT "mp" "mntflags" "l" 228Unmount a file system specified by the mount structure 229.Fa mp . 230The argument 231.Fa l 232is the calling lwp. 233.Fn VFS_UNMOUNT 234performs any file system type specific operations required before the 235file system is unmounted, such are flushing buffers. 236If MNT_FORCE is specified in the flags 237.Fa mntflags 238then open files are forcibly closed. 239The function also deallocates space associated with data structure 240that were allocated for the file system when it was mounted. 241.It Fn VFS_ROOT "mp" "vpp" 242Get the root vnode of the file system specified by the mount 243structure 244.Fa mp . 245The vnode is returned in the address given by 246.Fa vpp . 247This function is used by the pathname translation algorithms when a 248vnode that has been covered by a mounted file system is encountered. 249While resolving the pathname, the pathname translation algorithm will 250have to go through the directory tree in the file system associated 251with that mount point and therefore requires the root vnode of the 252file system. 253.It Fn VFS_QUOTACTL "mp" "cmds" "uid" "arg" "l" 254Query/modify user space quotas for the file system specified by the 255mount structure 256.Fa mp . 257The argument specifies the control command to perform. 258The userid is specified in 259.Fa id , 260the calling lwp is 261.Fa l 262and 263.Fa arg 264allows command-specific data to be returned to the system call 265interface. 266.Fn VFS_QUOTACTL 267is the file system type specific implementation of the 268.Xr quotactl 2 269system call. 270.It Fn VFS_STATVFS "mp" "sbp" "l" 271Get file system statistics for the file system specified by the mount 272structure 273.Fa mp . 274The argument 275.Fa l 276is the calling lwp. 277A statvfs structure filled with the statistics is returned in 278.Fa sbp . 279.Fn VFS_STATVFS 280is the file system type specific implementation of the 281.Xr statvfs 2 282and 283.Xr fstatvfs 2 284system calls. 285.It Fn VFS_SYNC "mp" "waitfor" "cred" "l" 286Flush file system I/O buffers for the file system specified by the mount 287structure 288.Fa mp . 289The 290.Fa waitfor 291argument indicates whether a partial flush or complete flush should be 292performed. 293The arguments 294.Fa l 295and 296.Fa cred 297specific the calling lwp and its credentials, respectively. 298.Fn VFS_SYNC 299does not provide any return value since the operation can never fail. 300.It Fn VFS_VGET "mp" "ino" "vpp" 301Get vnode for a file system type specific file id 302.Fa ino 303for the file system specified by the mount structure 304.Fa mp . 305The vnode is returned in the address specified 306.Fa vpp . 307The function is optional for file systems which have a unique id 308number for every file in the file system. 309It is used internally by the UFS file system and also by the NFSv3 310server to implement the READDIRPLUS nfs call. 311If the file system does not support this function, it should return 312.Er EOPNOTSUPP . 313.It Fn VFS_FHTOVP "mp" "fhp" "vpp" 314Get the vnode for the file handle 315.Fa fhp 316in the file system specified by the mount structure 317.Fa mp . 318The locked vnode is returned in 319.Fa vpp . 320.Pp 321When exporting, the call to 322.Fn VFS_FHTOVP 323should follow a call to 324.Fn netexport_check , 325which checks if the file is accessable to the client. 326.Pp 327If file handles are not supported by the file system, this function 328must return 329.Er EOPNOTSUPP . 330.It Fn VFS_VPTOFH "vp" "fhp" "fh_size" 331Get a file handle for the vnode specified by 332.Fa vp . 333The file handle is returned in 334.Fa fhp . 335The contents of the file handle are defined by the file system and are 336not examined by any other subsystems. 337It should contain enough information to uniquely identify a file within 338the file system as well as noticing when a file has been removed and 339the file system resources have been recycled for a new file. 340.Pp 341The parameter 342.Fa fh_size 343points to the container size for the file handle. 344This parameter should be updated to the size of the finished file handle. 345Note that it is legal to call this function with 346.Fa fhp 347set to 348.Dv NULL 349in case 350.Fa fh_size 351is zero. 352In case 353.Fa fh_size 354indicates a storage space too small, the storage space required for 355the file handle corresponding to 356.Fa vp 357should be filled in and 358.Er E2BIG 359should be returned. 360.Pp 361If file handles are not supported by the file system, this function 362must return 363.Er EOPNOTSUPP . 364.It Fn VFS_SNAPSHOT "mp" "vp" "ts" 365Take a snapshot of the file system specified by the mount structure 366.Fa mp 367and make it accessible through the locked vnode 368.Fa vp . 369If 370.Fa ts 371is not 372.Dv NULL 373it will receive the time this snapshot was taken. 374If the file system does not support this function, it should return 375.Er EOPNOTSUPP . 376.It Fn VFS_SUSPENDCTL "mp" "cmd" 377Suspend or resume all operations on this file system. 378.Fa cmd 379is either 380.Dv SUSPEND_SUSPEND 381to suspend or 382.Dv SUSPEND_RESUME 383to resume operations. 384If the file system does not support this function, it should return 385.Er EOPNOTSUPP . 386.El 387.Sh CODE REFERENCES 388This section describes places within the 389.Nx 390source tree where actual code implementing or using the vfs 391operations can be found. 392All pathnames are relative to 393.Pa /usr/src . 394.Pp 395The vfs operations are implemented within the files 396.Pa sys/kern/vfs_subr.c 397and 398.Pa sys/kern/vfs_init.c . 399.Sh SEE ALSO 400.Xr intro 9 , 401.Xr namei 9 , 402.Xr vfs 9 , 403.Xr vfssubr 9 , 404.Xr vnode 9 , 405.Xr vnodeops 9 406.Sh HISTORY 407The vfs operations vector, its functions and the corresponding macros 408appeared in 409.Bx 4.3 . 410