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