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