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