VFSOPS(9)              NetBSD Kernel Developer's Manual              VFSOPS(9)

NAME
     vfsops, VFS_MOUNT, VFS_START, VFS_UNMOUNT, VFS_ROOT, VFS_QUOTACTL,
     VFS_STATVFS, VFS_SYNC, VFS_VGET, VFS_FHTOVP, VFS_VPTOFH, VFS_SNAPSHOT,
     VFS_SUSPENDCTL -- kernel file system interface

SYNOPSIS
     #include <sys/param.h>
     #include <sys/mount.h>
     #include <sys/vnode.h>

     int
     VFS_MOUNT(struct mount *mp, const char *path, void *data, size_t *dlen);

     int
     VFS_START(struct mount *mp, int flags);

     int
     VFS_UNMOUNT(struct mount *mp, int mntflags);

     int
     VFS_ROOT(struct mount *mp, struct vnode **vpp);

     int
     VFS_QUOTACTL(struct mount *mp, int cmds, uid_t uid, void *arg);

     int
     VFS_STATVFS(struct mount *mp, struct statvfs *sbp);

     int
     VFS_SYNC(struct mount *mp, int waitfor, kauth_cred_t cred);

     int
     VFS_VGET(struct mount *mp, ino_t ino, struct vnode **vpp);

     int
     VFS_FHTOVP(struct mount *mp, struct fid *fhp, struct vnode **vpp);

     int
     VFS_VPTOFH(struct vnode *vp, struct fid *fhp, size_t *fh_size);

     int
     VFS_SNAPSHOT(struct mount *mp, struct vnode *vp, struct timespec *ts);

     int
     VFS_SUSPENDCTL(struct mount *mp, int cmd);

DESCRIPTION
     In a similar fashion to the 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 know-
     ing its construction or type.

     All supported file systems in the kernel have an entry in the
     vfs_list_initial table.  This table is generated by config(1) and is a
     NULL-terminated list of 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 corre-
     sponding invocation macro, and a description of the element.

     Vector element          Macro         Description
     int  (*vfs_mount)()     VFS_MOUNT     Mount a file system
     int  (*vfs_start)()     VFS_START     Make operational
     int  (*vfs_unmount)()   VFS_UMOUNT    Unmount a file system
     int  (*vfs_root)()      VFS_ROOT      Get the file system root vnode
     int  (*vfs_quotactl)()  VFS_QUOTACTL  Query/modify space quotas
     int  (*vfs_statvfs)()   VFS_STATVFS   Get file system statistics
     int  (*vfs_sync)()      VFS_SYNC      Flush file system buffers
     int  (*vfs_vget)()      VFS_VGET      Get vnode from file id
     int  (*vfs_fhtovp)()    VFS_FHTOVP    NFS file handle to vnode lookup
     int  (*vfs_vptofh)()    VFS_VPTOFH    Vnode to NFS file handle lookup
     void (*vfs_init)()      -             Initialize file system
     void (*vfs_reinit)()    -             Reinitialize file system
     void (*vfs_done)()      -             Cleanup unmounted file system
     int  (*vfs_mountroot)() -             Mount the root file system
     int  (*vfs_snapshot)()  VFS_SNAPSHOT  Take a snapshot
     int  (*vfs_suspendctl)()              VFS_SUSPENDCTL              Suspend or resume

     Some additional non-function members of the vfsops structure are the file
     system name vfs_name and a reference count 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.
     vfs_reinit, vfs_mountroot, vfs_fhtovp, and vfs_vptofh may be NULL.

     At system boot, each file system with an entry in vfs_list_initial is
     established and initialized.  Each initialized file system is recorded by
     the kernel in the list vfs_list and the file system specific initializa-
     tion function vfs_init in its vfsops vector is invoked.  When the file
     system is no longer needed vfs_done is invoked to run file system spe-
     cific cleanups and the file system is removed from the kernel list.

     At system boot, the root file system is mounted by invoking the file sys-
     tem type specific vfs_mountroot function in the vfsops vector.  All file
     systems that can be mounted as a root file system must define this func-
     tion.  It is responsible for initializing to list of mount structures for
     all future mounted file systems.

     Kernel state which affects a specific file system type can be queried and
     modified using the sysctl(8) interface.

FUNCTIONS
     VFS_MOUNT(mp, path, data, dlen)
              Mount a file system specified by the mount structure mp on the
              mount point described by path.  The argument data contains file
              system type specific data, while the argument dlen points to a
              location specifying the length of the data.

              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 MNT_UPDATE is set in 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 specify-
              ing MNT_GETARGS.  If neither MNT_UPDATE or MNT_GETARGS are spec-
              ified, a new file system will attempted to be mounted.

     VFS_START(mp, flags)
              Make the file system specified by the mount structure mp opera-
              tional.  The argument flags is a set of flags for controlling
              the operation of VFS_START().  This function is invoked after
              VFS_MOUNT() and before the first access to the file system.

     VFS_UNMOUNT(mp, mntflags)
              Unmount a file system specified by the mount structure mp.
              VFS_UNMOUNT() performs any file system type specific operations
              required before the file system is unmounted, such are flushing
              buffers.  If MNT_FORCE is specified in the flags 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.

     VFS_ROOT(mp, vpp)
              Get the root vnode of the file system specified by the mount
              structure mp.  The vnode is returned in the address given by
              vpp.  This function is used by the pathname translation algo-
              rithms when a vnode that has been covered by a mounted file sys-
              tem 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 there-
              fore requires the root vnode of the file system.

     VFS_QUOTACTL(mp, cmds, uid, arg)
              Query/modify user space quotas for the file system specified by
              the mount structure mp.  The argument specifies the control com-
              mand to perform.  The userid is specified in id and arg allows
              command-specific data to be returned to the system call inter-
              face.  VFS_QUOTACTL() is the file system type specific implemen-
              tation of the quotactl(2) system call.

     VFS_STATVFS(mp, sbp)
              Get file system statistics for the file system specified by the
              mount structure mp.  A statvfs structure filled with the statis-
              tics is returned in sbp.  VFS_STATVFS() is the file system type
              specific implementation of the statvfs(2) and fstatvfs(2) system
              calls.

     VFS_SYNC(mp, waitfor, cred)
              Flush file system I/O buffers for the file system specified by
              the mount structure mp.  The waitfor argument indicates whether
              a partial flush or complete flush should be performed.  The
              argument cred specifies the calling credentials.  VFS_SYNC()
              does not provide any return value since the operation can never
              fail.

     VFS_VGET(mp, ino, vpp)
              Get vnode for a file system type specific file id ino for the
              file system specified by the mount structure mp.  The vnode is
              returned in the address specified 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 EOPNOTSUPP.

     VFS_FHTOVP(mp, fhp, vpp)
              Get the vnode for the file handle fhp in the file system speci-
              fied by the mount structure mp.  The locked vnode is returned in
              vpp.

              When exporting, the call to VFS_FHTOVP() should follow a call to
              netexport_check(), which checks if the file is accessible to the
              client.

              If file handles are not supported by the file system, this func-
              tion must return EOPNOTSUPP.

     VFS_VPTOFH(vp, fhp, fh_size)
              Get a file handle for the vnode specified by vp.  The file han-
              dle is returned in 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.

              The parameter 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 func-
              tion with fhp set to NULL in case fh_size is zero.  In case
              fh_size indicates a storage space too small, the storage space
              required for the file handle corresponding to vp should be
              filled in and E2BIG should be returned.

              If file handles are not supported by the file system, this func-
              tion must return EOPNOTSUPP.

     VFS_SNAPSHOT(mp, vp, ts)
              Take a snapshot of the file system specified by the mount struc-
              ture mp and make it accessible through the locked vnode vp.  If
              ts is not NULL it will receive the time this snapshot was taken.
              If the file system does not support this function, it should
              return EOPNOTSUPP.

     VFS_SUSPENDCTL(mp, cmd)
              Suspend or resume all operations on this file system.  cmd is
              either SUSPEND_SUSPEND to suspend or SUSPEND_RESUME to resume
              operations.  If the file system does not support this function,
              it should return EOPNOTSUPP.

CODE REFERENCES
     This section describes places within the NetBSD source tree where actual
     code implementing or using the vfs operations can be found.  All path-
     names are relative to /usr/src.

     The vfs operations are implemented within the files sys/kern/vfs_subr.c,
     sys/kern/vfs_subr2.c and sys/kern/vfs_init.c.

SEE ALSO
     intro(9), namei(9), vfs(9), vfssubr(9), vnode(9), vnodeops(9)

HISTORY
     The vfs operations vector, its functions and the corresponding macros
     appeared in 4.3BSD.

NetBSD 5.0_STABLE              January 24, 2008              NetBSD 5.0_STABLE
