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