.\"     $NetBSD: vfsops.9,v 1.53 2020/08/28 07:28:59 hannken Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Gregory McGarry.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 7, 2020
.Dt VFSOPS 9
.Os
.Sh NAME
.Nm vfsops ,
.Nm VFS_MOUNT ,
.Nm VFS_START ,
.Nm VFS_UNMOUNT ,
.Nm VFS_ROOT ,
.Nm VFS_QUOTACTL ,
.Nm VFS_STATVFS ,
.Nm VFS_SYNC ,
.Nm VFS_VGET ,
.Nm VFS_LOADVNODE ,
.Nm VFS_NEWVNODE ,
.Nm VFS_FHTOVP ,
.Nm VFS_VPTOFH ,
.Nm VFS_SNAPSHOT ,
.Nm VFS_SUSPENDCTL
.Nd kernel file system interface
.Sh SYNOPSIS
.In sys/param.h
.In sys/mount.h
.In sys/vnode.h
.Ft int
.Fo VFS_MOUNT
.Fa "struct mount *mp" "const char *path" "void *data" "size_t *dlen"
.Fc
.Ft int
.Fn VFS_START "struct mount *mp" "int flags"
.Ft int
.Fn VFS_UNMOUNT "struct mount *mp" "int mntflags"
.Ft int
.Fn VFS_ROOT "struct mount *mp" "int lktype" "struct vnode **vpp"
.Ft int
.Fn VFS_QUOTACTL "struct mount *mp" "struct quotactl_args *args"
.Ft int
.Fn VFS_STATVFS "struct mount *mp" "struct statvfs *sbp"
.Ft int
.Fn VFS_SYNC "struct mount *mp" "int waitfor" "kauth_cred_t cred"
.Ft int
.Fn VFS_VGET "struct mount *mp" "ino_t ino" "int lktype" "struct vnode **vpp"
.Ft int
.Fn VFS_LOADVNODE "struct mount *mp" "struct vnode *vp" "const void *key" "size_t key_len" "const void **new_key"
.Ft int
.Fn VFS_NEWVNODE "struct mount *mp" "struct vnode *dvp" "struct vnode *vp" "struct vattr *vap" "kauth_cred_t cred" "void *extra" "size_t *key_len" "const void **new_key"
.Ft int
.Fn VFS_FHTOVP "struct mount *mp" "struct fid *fhp" "int lktype" "struct vnode **vpp"
.Ft int
.Fn VFS_VPTOFH "struct vnode *vp" "struct fid *fhp" "size_t *fh_size"
.Ft int
.Fn VFS_SNAPSHOT "struct mount *mp" "struct vnode *vp" "struct timespec *ts"
.Ft int
.Fn VFS_SUSPENDCTL "struct mount *mp" "int cmd"
.Sh DESCRIPTION
In a similar fashion to the
.Xr vnode 9
interface, all operations that are done on a file system are conducted
through a single interface that allows the system to carry out
operations on a file system without knowing its construction or type.
.Pp
All supported file systems in the kernel have an entry in the
.Va vfs_list_initial
table.
This table is generated by
.Xr config 1
and is a
.Dv NULL Ns No -terminated
list of
.Vt vfsops
structures.
The vfsops structure describes the operations that can be done to a
specific file system type.
The following table lists the elements of the vfsops vector, the
corresponding invocation macro, and a description of the element.
.Pp
.Bl -column "int (*vfs_suspendctl)()" "VFS_SUSPENDCTL" -compact
.It Sy Vector element Ta Sy Macro Ta Sy Description
.\"
.It int (*vfs_mount)() \
Ta Dv VFS_MOUNT \
Ta Mount a file system
.\"
.It int (*vfs_start)() \
Ta Dv VFS_START \
Ta Make operational
.\"
.It int (*vfs_unmount)() \
Ta Dv VFS_UNMOUNT \
Ta Unmount a file system
.\"
.It int (*vfs_root)() \
Ta Dv VFS_ROOT \
Ta Get the file system root vnode
.\"
.It int (*vfs_quotactl)() \
Ta Dv VFS_QUOTACTL \
Ta Query/modify space quotas
.\"
.It int (*vfs_statvfs)() \
Ta Dv VFS_STATVFS \
Ta Get file system statistics
.\"
.It int (*vfs_sync)() \
Ta Dv VFS_SYNC \
Ta Flush file system buffers
.\"
.It int (*vfs_vget)() \
Ta Dv VFS_VGET \
Ta Get vnode from file id
.\"
.It int (*vfs_loadvnode)() \
Ta Dv VFS_LOADVNODE \
Ta Initialize vnode with file
.\"
.It int (*vfs_newvnode)() \
Ta Dv VFS_NEWVNODE \
Ta Initialize vnode with new file
.\"
.It int (*vfs_fhtovp)() \
Ta Dv VFS_FHTOVP \
Ta NFS file handle to vnode lookup
.\"
.It int (*vfs_vptofh)() \
Ta Dv VFS_VPTOFH \
Ta Vnode to NFS file handle lookup
.\"
.It void (*vfs_init)() \
Ta \- \
Ta Initialize file system
.\"
.It void (*vfs_reinit)() \
Ta \- \
Ta Reinitialize file system
.\"
.It void (*vfs_done)() \
Ta \- \
Ta Cleanup unmounted file system
.\"
.It int (*vfs_mountroot)() \
Ta \- \
Ta Mount the root file system
.\"
.It int (*vfs_snapshot)() \
Ta Dv VFS_SNAPSHOT \
Ta Take a snapshot
.\"
.It int (*vfs_suspendctl)() \
Ta Dv VFS_SUSPENDCTL \
Ta Suspend or resume
.El
.Pp
Some additional non-function members of the vfsops structure are the
file system name
.Fa vfs_name
and a reference count
.Fa vfs_refcount .
It is not mandatory for a file system type to support a particular
operation, but it must assign each member function pointer to a
suitable function to do the minimum required of it.
In most cases, such functions either do nothing or return an error
value to the effect that it is not supported.
.Fa vfs_reinit ,
.Fa vfs_mountroot ,
.Fa vfs_fhtovp ,
and
.Fa vfs_vptofh
may
be
.Dv NULL .
.Pp
At system boot, each file system with an entry in
.Va vfs_list_initial
is established and initialized.
Each initialized file system is recorded by the kernel in the list
.Va vfs_list
and the file system specific initialization function
.Fa vfs_init
in its vfsops vector is invoked.
When the file system is no longer needed
.Fa vfs_done
is invoked to run file system specific cleanups and the file system is
removed from the kernel list.
.Pp
At system boot, the root file system is mounted by invoking the file
system type specific
.Fa vfs_mountroot
function in the vfsops vector.
All file systems that can be mounted as a root file system must define
this function.
It is responsible for initializing to list of mount structures for
all future mounted file systems.
.Pp
Kernel state which affects a specific file system type can be
queried and modified using the
.Xr sysctl 8
interface.
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn VFS_MOUNT "mp" "path" "data" "dlen"
Mount a file system specified by the mount structure
.Fa mp
on the mount point described by
.Fa path .
The argument
.Fa data
contains file system type specific data, while the argument
.Fa dlen
points to a location specifying the length of the data.
.Pp
.Fn VFS_MOUNT
initializes the mount structure for the mounted file system.
This structure records mount-specific information for the file system and
records the list of vnodes associated with the file system.
This function is invoked both to mount new file systems and to change the
attributes of an existing file system.
If the flag
.Dv MNT_UPDATE
is set in
.Va mp->mnt_flag ,
the file system should update its state.
This can be used, for instance, to convert a read-only file system to
read-write.
The current attributes for a mounted file system can be fetched by
specifying
.Dv MNT_GETARGS .
If neither
.Dv MNT_UPDATE
or
.Dv MNT_GETARGS
are specified, a new file system will attempted to be mounted.
.It Fn VFS_START "mp" "flags"
Make the file system specified by the mount structure
.Fa mp
operational.
The argument
.Fa flags
is a set of flags for controlling the operation of
.Fn VFS_START .
This function is invoked after
.Fn VFS_MOUNT
and before the first access to the file system.
.It Fn VFS_UNMOUNT "mp" "mntflags"
Unmount a file system specified by the mount structure
.Fa mp .
.Fn VFS_UNMOUNT
performs any file system type specific operations required before the
file system is unmounted, such are flushing buffers.
If
.Dv MNT_FORCE
is specified in the flags
.Fa mntflags
then open files are forcibly closed.
The function also deallocates space associated with data structure
that were allocated for the file system when it was mounted.
.It Fn VFS_ROOT "mp" "lktype" "vpp"
Get the root vnode of the file system specified by the mount
structure
.Fa mp .
The vnode is returned in the address given by
.Fa vpp ,
with lock type
.Fa lktype .
.Fa lktype
can be
.Dv LK_NONE ,
or
.Dv LK_SHARED ,
or
.Dv LK_EXCLUSIVE .
This function is used by the pathname translation algorithms when a
vnode that has been covered by a mounted file system is encountered.
While resolving the pathname, the pathname translation algorithm will
have to go through the directory tree in the file system associated
with that mount point and therefore requires the root vnode of the
file system.
.It Fn VFS_QUOTACTL "mp" "args"
Query/modify user space quotas for the file system specified by the
mount structure
.Fa mp .
The argument structure provides the operation ID and arguments to
perform.
This is the same interface as documented in
.Xr __quotactl 2
except that the file system argument has been resolved.
All
.Xr copyin 9
and
.Xr copyout 9
processing is handled by code above the file system.
.It Fn VFS_STATVFS "mp" "sbp"
Get file system statistics for the file system specified by the mount
structure
.Fa mp .
A statvfs structure filled with the statistics is returned in
.Fa sbp .
.Fn VFS_STATVFS
is the file system type specific implementation of the
.Xr statvfs 2
and
.Xr fstatvfs 2
system calls.
.It Fn VFS_SYNC "mp" "waitfor" "cred"
Flush file system I/O buffers for the file system specified by the mount
structure
.Fa mp .
The
.Fa waitfor
argument indicates whether a partial flush or complete flush should be
performed.
The argument
.Fa cred
specifies the calling credentials.
.Fn VFS_SYNC
does not provide any return value since the operation can never fail.
.It Fn VFS_VGET "mp" "ino" "lktype" "vpp"
Get vnode for a file system type specific file id
.Fa ino
for the file system specified by the mount structure
.Fa mp ,
with lock type
.Fa lktype .
.Fa lktype
can be
.Dv LK_NONE ,
or
.Dv LK_SHARED ,
or
.Dv LK_EXCLUSIVE .
The vnode is returned in the address specified
.Fa vpp .
The function is optional for file systems which have a unique id
number for every file in the file system.
It is used internally by the UFS file system and also by the NFSv3
server to implement the READDIRPLUS NFS call.
If the file system does not support this function, it should return
.Er EOPNOTSUPP .
.It Fn VFS_LOADVNODE "mp" "vp" "key" "key_len" "new_key"
Initialise the vnode
.Fa vp
with the file identified by the arguments
.Fa key
and
.Fa key_len
for the file system specified by the mount structure
.Fa mp .
.Pp
The new key is returned in the address specified by
.Fa new_key .
.Pp
Caller of this function assures no other thread will try to load this file.
.It Fn VFS_NEWVNODE "mp" "dvp" "vp" "vap" "cred" "extra" "key_len" "new_key"
Initialise the vnode
.Fa vp
with a new file for the file system specified by the mount structure
.Fa mp .
.Pp
The argument
.Fa dvp
points to the directory to create the file in.
.Pp
The argument
.Fa vap
points to the attributes for the file to create.
.Pp
The argument
.Fa cred
holds the credentials for the file to create.
.Pp
The argument
.Fa extra
allows the caller to pass more information about the file to create.
.Pp
The key for the file is returned in the addresses specified by
.Fa key_len
and
.Fa new_key .
.It Fn VFS_FHTOVP "mp" "fhp" "lktype" "vpp"
Get the vnode for the file handle
.Fa fhp
in the file system specified by the mount structure
.Fa mp ,
with lock type
.Fa lktype .
.Fa lktype
can be
.Dv LK_NONE ,
or
.Dv LK_SHARED ,
or
.Dv LK_EXCLUSIVE .
The locked vnode is returned in
.Fa vpp .
.Pp
When exporting, the call to
.Fn VFS_FHTOVP
should follow a call to
.Fn netexport_check ,
which checks if the file is accessible to the client.
.Pp
If file handles are not supported by the file system, this function
must return
.Er EOPNOTSUPP .
.It Fn VFS_VPTOFH "vp" "fhp" "fh_size"
Get a file handle for the vnode specified by
.Fa vp .
The file handle is returned in
.Fa fhp .
The contents of the file handle are defined by the file system and are
not examined by any other subsystems.
It should contain enough information to uniquely identify a file within
the file system as well as noticing when a file has been removed and
the file system resources have been recycled for a new file.
.Pp
The parameter
.Fa fh_size
points to the container size for the file handle.
This parameter should be updated to the size of the finished file handle.
Note that it is legal to call this function with
.Fa fhp
set to
.Dv NULL
in case
.Fa fh_size
is zero.
In case
.Fa fh_size
indicates a storage space too small, the storage space required for
the file handle corresponding to
.Fa vp
should be filled in and
.Er E2BIG
should be returned.
.Pp
If file handles are not supported by the file system, this function
must return
.Er EOPNOTSUPP .
.It Fn VFS_SNAPSHOT "mp" "vp" "ts"
Take a snapshot of the file system specified by the mount structure
.Fa mp
and make it accessible through the locked vnode
.Fa vp .
If
.Fa ts
is not
.Dv NULL
it will receive the time this snapshot was taken.
If the file system does not support this function, it should return
.Er EOPNOTSUPP .
.It Fn VFS_SUSPENDCTL "mp" "cmd"
Suspend or resume all operations on this file system.
.Fa cmd
is either
.Dv SUSPEND_SUSPEND
to suspend or
.Dv SUSPEND_RESUME
to resume operations.
If the file system does not support this function, it should return
.Er EOPNOTSUPP .
.El
.Sh CODE REFERENCES
The vfs operations are implemented within the files
.Pa sys/kern/vfs_subr.c
and
.Pa sys/kern/vfs_init.c .
.Sh SEE ALSO
.Xr intro 9 ,
.Xr namei 9 ,
.Xr vfs 9 ,
.Xr vfssubr 9 ,
.Xr vnode 9 ,
.Xr vnodeops 9
.Sh HISTORY
The vfs operations vector, its functions and the corresponding macros
appeared in
.Bx 4.3 .