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