1.\" $NetBSD: vfsops.9,v 1.17 2004/06/20 18:55:58 hannken 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 June 20, 2004 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_STATFS , 48.Nm VFS_STATFS , 49.Nm VFS_SYNC , 50.Nm VFS_VGET , 51.Nm VFS_FHTOVP , 52.Nm VFS_VPTOFH , 53.Nm VFS_CHECKEXP , 54.Nm VFS_SNAPSHOT 55.Nd kernel file system interface 56.Sh SYNOPSIS 57.In sys/param.h 58.In sys/mount.h 59.In sys/vnode.h 60.Ft int 61.Fn VFS_MOUNT "struct mount *mp" "const char *path" "void *data" \ 62"struct nameidata *ndp" "struct proc *p" 63.Ft int 64.Fn VFS_START "struct mount *mp" "int flags" "struct proc *p" 65.Ft int 66.Fn VFS_UNMOUNT "struct mount *mp" "int mntflags" "struct proc *p" 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" \ 71"caddr_t arg" "struct proc *p" 72.Ft int 73.Fn VFS_STATFS "struct mount *mp" "struct statfs *sbp" "struct proc *p" 74.Ft int 75.Fn VFS_SYNC "struct mount *mp" "int waitfor" "struct ucred *cred" \ 76"struct proc *p" 77.Ft int 78.Fn VFS_VGET "struct mount *mp" "ino_t ino" "struct vnode **vpp" 79.Ft int 80.Fn VFS_FHTOVP "struct mount *mp" "struct fid *fhp" "struct vnode **vpp" 81.Ft int 82.Fn VFS_VPTOFH "struct vnode *vp" "struct fid *fhp" 83.Ft int 84.Fn VFS_CHECKEXP "struct mount *mp" "struct mbuf *nam" \ 85"int *extflagsp" "struct ucred **credanonp" 86.Ft int 87.Fn VFS_SNAPSHOT "struct mount *mp" "struct vnode *vp" "struct timespec *ts" 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 8 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 list 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_statfs)() VFS_STATFS 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_checkexp)() VFS_CHECKEXP Check if file system is exported 130int (*vfs_snapshot)() VFS_SNAPSHOT Take a snapshot 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 144and 145.Em vfs_mountroot 146may 147be 148.Dv NULL . 149.Pp 150At system boot, each file system with an entry in 151.Va vfs_list_initial 152is established and initialised. 153Each initialised file system is recorded by the kernel in the list 154.Va vfs_list 155and the file system specific initialisation function 156.Em vfs_init 157in its vfsops vector is invoked. 158When the file system is not longer needed 159.Em vfs_done 160is invoked to run file system specific cleanups and the file system is 161removed from the kernel list. 162.Pp 163At system boot, the root filesystem is mounted by invoking the file 164system type specific 165.Em vfs_mountroot 166function in the vfsops vector. 167All filesystems that can be mounted as a root file system must define 168this function. 169It is responsible for initialising to list of mount structures for 170all future mounted file systems. 171.Pp 172Kernel state which affects a specific file system type can be 173queried and modified using the 174.Xr sysctl 8 175interface. 176.Sh FUNCTIONS 177.Bl -tag -width compact 178.It Fn VFS_MOUNT "mp" "path" "data" "ndp" "p" 179Mount a file system specified by the mount structure 180.Fa mp 181on the mount point described by 182.Fa path . 183The argument 184.Fa data 185contains file system type specific data and is read into the kernel 186using 187.Xr copyin 9 . 188The argument 189.Fa ndp 190contains the result of a 191.Xr namei 9 192call on the pathname of the mount point and 193.Fa p 194is the calling process. 195.Fn VFS_MOUNT 196initialises the mount structure for the mounted file system. 197This structure records mount-specific information for the file system and 198records the list of vnodes associated with the file system. 199This function is invoked both to mount new file systems and to change the 200attributes of an existing file system. 201If the MNT_UPDATE flag is set in 202.Em mp-\*[Gt]mnt_flag 203then the filesystem should update its internal state from the value of 204.Em mp-\*[Gt]mnt_flag . 205This can be used, for instance, to convert a read-only filesystem to 206read-write. 207If the MNT_UPDATE flag is not specified, then this is a newly 208mounted filesystem. 209.It Fn VFS_START "mp" "flags" "p" 210Make the file system specified by the mount structure 211.Fa mp 212operational. 213The argument 214.Fa p 215is the calling process. 216The argument 217.Fa flags 218is a set of flags for controlling the operation of 219.Fn VOP_START . 220This function is invoked after 221.Fn VFS_MOUNT 222and before the first access to the file system. 223.It Fn VFS_UNMOUNT "mp" "mntflags" "p" 224Unmount a file system specified by the mount structure 225.Fa mp . 226The argument 227.Fa p 228is the calling process. 229.Fn VFS_UNMOUNT 230performs any file system type specific operations required before the 231file system is unmounted, such are flushing buffers. 232If MNT_FORCE is specified in the flags 233.Fa mntflags 234then open files are forcibly closed. 235The function also deallocates space associated with data structure 236that were allocated for the file system when it was mounted. 237.It Fn VFS_ROOT "mp" "vpp" 238Get the root vnode of the file system specified by the mount 239structure 240.Fa mp . 241The vnode is returned in the address given by 242.Fa vpp . 243This function is used by the pathname translation algorithms when a 244vnode that has been covered by a mounted file system is encountered. 245While resolving the pathname, the pathname translation algorithm will 246have to go through the directory tree in the file system associated 247with that mount point and therefore requires the root vnode of the 248file system. 249.It Fn VFS_QUOTACTL "mp" "cmds" "uid" "arg" "p" 250Query/modify user space quotas for the file system specified by the 251mount structure 252.Fa mp . 253The argument specifies the control command to perform. 254The userid is specified in 255.Fa id , 256the calling process is 257.Fa p 258and 259.Fa arg 260allows command-specific data to be returned to the system call 261interface. 262.Fn VFS_QUOTACTL 263is the file system type specific implementation of the 264.Xr quotactl 2 265system call. 266.It Fn VFS_STATFS "mp" "sbp" "p" 267Get file system statistics for the file system specified by the mount 268structure 269.Fa mp . 270The argument 271.Fa p 272is the calling process. 273A statfs structure filled with the statistics is returned in 274.Fa sbp . 275.Fn VFS_STATFS 276is the file system type specific implementation of the 277.Xr statfs 2 278and 279.Xr fstatfs 2 280system calls. 281.It Fn VFS_SYNC "mp" "waitfor" "cred" "p" 282Flush file system I/O buffers for the file system specified by the mount 283structure 284.Fa mp . 285The 286.Fa waitfor 287argument indicates whether a partial flush or complete flush should be 288performed. 289The arguments 290.Fa p 291and 292.Fa cred 293specific the calling process and its credentials respectively. 294.Fn VFS_SYNC 295does not provide any return value since the operation can never fail. 296.It Fn VFS_VGET "mp" "ino" "vpp" 297Get vnode for a file system type specific file id 298.Fa ino 299for the file system specified by the mount structure 300.Fa mp . 301The vnode is returned in the address specified 302.Fa vpp . 303The function is optional for file systems which have a unique id 304number for every file in the file system. 305It is used internally by the UFS file system and also by the NFSv3 306server to implement the READDIRPLUS nfs call. 307If the file system does not support this function, it should return 308.Er EOPNOTSUPP . 309.It Fn VFS_FHTOVP "mp" "fhp" "vpp" 310Get the vnode for the NFS file specified by the file handle 311.Fa fhp 312in the file system specified by the mount structure 313.Fa mp . 314The locked vnode is returned in 315.Fa vpp . 316.Pp 317A call to 318.Fn VFS_FHTOVP 319should generally be followed by a call to 320.Fn VFS_CHECKEXP 321to check if the file is accessable to the client. 322.It Fn VFS_VPTOFH "vp" "fhp" 323Get a unique NFS file handle for the file specified by the vnode 324.Fa vp . 325The file handle is returned in 326.Fa fhp . 327The contents of the file handle are defined by the file system and are 328not examined by any other subsystems. 329It should contain enough information to uniquely identify a file within 330the file system as well as noticing when a file has been removed and 331the file system resources have been recycled for a new file. 332.It Fn VFS_CHECKEXP "mp" "nam" "extflagsp" "credanonp" 333Check if the file system specified by the mount structure 334.Fa mp 335is exported to a client with anonymous credentials 336.Fa credanonp . 337The argument 338.Fa nam 339is an mbuf containing the network address of the client. 340The return parameters for the export flags for the client are returned 341in the address specified by 342.Fa exflagsp . 343This function is used by the NFS server. 344It is generally invoked before 345.Fn VFS_FHTOVP 346to validate that client has access to the file system. 347The file system should call 348.Fn vfs_export_lookup 349with the address of an appropriate netexport structure and the address 350of the client to verify that the client can access this file system. 351.It Fn VFS_SNAPSHOT "mp" "vp" "ts" 352Take a snapshot of the file system specified by the mount structure 353.Fa mp 354and make it accessible through the locked vnode 355.Fa vp . 356If 357.Fa ts 358is not 359.Dv NULL 360it will receive the time this snapshot was taken. 361If the file system does not support this function, it should return 362.Er EOPNOTSUPP . 363.El 364.Sh CODE REFERENCES 365This section describes places within the 366.Nx 367source tree where actual code implementing or using the vfs 368operations can be found. 369All pathnames are relative to 370.Pa /usr/src . 371.Pp 372The vfs operations are implemented within the files 373.Pa sys/kern/vfs_subr.c 374and 375.Pa sys/kern/vfs_init.c . 376.Sh SEE ALSO 377.Xr intro 9 , 378.Xr namei 9 , 379.Xr vfs 9 , 380.Xr vfssubr 9 , 381.Xr vnode 9 , 382.Xr vnodeops 9 383.Sh HISTORY 384The vfs operations vector, its functions and the corresponding macros 385appeared in 386.Bx 4.3 . 387