506 lines
14 KiB
Groff
506 lines
14 KiB
Groff
.\" $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 .
|