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