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