Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


VNODEOPS(9)                Kernel Developer's Manual               VNODEOPS(9)

NAME
     vnodeops, VOP_LOOKUP, VOP_CREATE, VOP_MKNOD, VOP_OPEN, VOP_CLOSE,
     VOP_ACCESS, VOP_GETATTR, VOP_SETATTR, VOP_READ, VOP_WRITE, VOP_FALLOCATE,
     VOP_FDISCARD, VOP_IOCTL, VOP_FCNTL, VOP_POLL, VOP_KQFILTER, VOP_REVOKE,
     VOP_MMAP, VOP_FSYNC, VOP_SEEK, VOP_REMOVE, VOP_LINK, VOP_RENAME,
     VOP_MKDIR, VOP_RMDIR, VOP_SYMLINK, VOP_READDIR, VOP_READLINK,
     VOP_ABORTOP, VOP_INACTIVE, VOP_RECLAIM, VOP_LOCK, VOP_UNLOCK,
     VOP_ISLOCKED, VOP_BMAP, VOP_PRINT, VOP_PATHCONF, VOP_ADVLOCK,
     VOP_WHITEOUT, VOP_GETPAGES, VOP_PUTPAGES, VOP_STRATEGY, VOP_BWRITE,
     VOP_GETEXTATTR, VOP_SETEXTATTR, VOP_LISTEXTATTR, VOP_DELETEEXTATTR -
     vnode operations

SYNOPSIS
     #include <sys/param.h>
     #include <sys/buf.h>
     #include <sys/dirent.h>
     #include <sys/vnode.h>
     #include <sys/mount.h>
     #include <sys/namei.h>
     #include <sys/unistd.h>
     #include <sys/fcntl.h>
     #include <sys/lockf.h>
     #include <sys/extattr.h>

     int
     VOP_LOOKUP(struct vnode *dvp, struct vnode **vpp,
         struct componentname *cnp);

     int
     VOP_CREATE(struct vnode *dvp, struct vnode **vpp,
         struct componentname *cnp, struct vattr *vap);

     int
     VOP_MKNOD(struct vnode *dvp, struct vnode **vpp,
         struct componentname *cnp, struct vattr *vap);

     int
     VOP_OPEN(struct vnode *vp, int mode, kauth_cred_t cred);

     int
     VOP_CLOSE(struct vnode *vp, int fflag, kauth_cred_t cred);

     int
     VOP_ACCESS(struct vnode *vp, int mode, kauth_cred_t cred);

     int
     VOP_GETATTR(struct vnode *vp, struct vattr *vap, kauth_cred_t cred);

     int
     VOP_SETATTR(struct vnode *vp, struct vattr *vap, kauth_cred_t cred);

     int
     VOP_READ(struct vnode *vp, struct uio *uio, int ioflag,
         kauth_cred_t cred);

     int
     VOP_WRITE(struct vnode *vp, struct uio *uio, int ioflag,
         kauth_cred_t cred);

     int
     VOP_FALLOCATE(struct vnode *vp, off_t pos, off_t len);

     int
     VOP_FDISCARD(struct vnode *vp, off_t pos, off_t len);

     int
     VOP_IOCTL(struct vnode *vp, u_long command, void *data, int fflag,
         kauth_cred_t cred);

     int
     VOP_FCNTL(struct vnode *vp, u_int command, void *data, int fflag,
         kauth_cred_t cred);

     int
     VOP_POLL(struct vnode *vp, int events);

     int
     VOP_KQFILTER(struct vnode *vp, struct knote *kn);

     int
     VOP_REVOKE(struct vnode *vp, int flags);

     int
     VOP_MMAP(struct vnode *vp, vm_prot_t prot, kauth_cred_t cred);

     int
     VOP_FSYNC(struct vnode *vp, kauth_cred_t cred, int flags, off_t offlo,
         off_t offhi);

     int
     VOP_SEEK(struct vnode *vp, off_t oldoff, off_t newoff,
         kauth_cred_t cred);

     int
     VOP_REMOVE(struct vnode *dvp, struct vnode *vp,
         struct componentname *cnp);

     int
     VOP_LINK(struct vnode *dvp, struct vnode *vp, struct componentname *cnp);

     int
     VOP_RENAME(struct vnode *fdvp, struct vnode *fvp,
         struct componentname *fcnp, struct vnode *tdvp, struct vnode *tvp,
         struct componentname *tcnp);

     int
     VOP_MKDIR(struct vnode *dvp, struct vnode **vpp,
         struct componentname *cnp, struct vattr *vap);

     int
     VOP_RMDIR(struct vnode *dvp, struct vnode *vp,
         struct componentname *cnp);

     int
     VOP_SYMLINK(struct vnode *dvp, struct vnode **vpp,
         struct componentname *cnp, struct vattr *vap, char *target);

     int
     VOP_READDIR(struct vnode *vp, struct uio *uio, kauth_cred_t cred,
         int *eofflag, off_t **cookies, int *ncookies);

     int
     VOP_READLINK(struct vnode *vp, struct uio *uio, kauth_cred_t cred);

     int
     VOP_ABORTOP(struct vnode *dvp, struct componentname *cnp);

     int
     VOP_INACTIVE(struct vnode *vp);

     int
     VOP_RECLAIM(struct vnode *vp);

     int
     VOP_LOCK(struct vnode *vp, int flags);

     int
     VOP_UNLOCK(struct vnode *vp);

     int
     VOP_ISLOCKED(struct vnode *vp);

     int
     VOP_BMAP(struct vnode *vp, daddr_t bn, struct vnode **vpp, daddr_t *bnp,
         int *runp);

     int
     VOP_PRINT(struct vnode *vp);

     int
     VOP_PATHCONF(struct vnode *vp, int name, register_t *retval);

     int
     VOP_ADVLOCK(struct vnode *vp, void *id, int op, struct flock *fl,
         int flags);

     int
     VOP_WHITEOUT(struct vnode *dvp, struct componentname *cnp, int flags);

     int
     VOP_GETPAGES(struct vnode *vp, voff_t offset, struct vm_page **m,
         int *count, int centeridx, vm_prot_t access_type, int advice,
         int flags);

     int
     VOP_PUTPAGES(struct vnode *vp, voff_t offlo, voff_t offhi, int flags);

     int
     VOP_STRATEGY(struct vnode *vp, struct buf *bp);

     int
     VOP_BWRITE(struct vnode *vp, struct buf *bp);

     int
     VOP_GETEXTATTR(struct vnode *vp, int attrnamespace, const char *name,
         struct uio *uio, size_t *size, kauth_cred_t cred);

     int
     VOP_SETEXTATTR(struct vnode *vp, int attrnamespace, const char *name,
         struct uio *uio, kauth_cred_t cred);

     int
     VOP_LISTEXTATTR(struct vnode *vp, int attrnamespace, struct uio *uio,
         size_t *size, kauth_cred_t cred);

     int
     VOP_DELETEEXTATTR(struct vnode *vp, int attrnamespace, const char *name,
         kauth_cred_t cred);

     Not all header files are required for each function.

DESCRIPTION
     The vnode operations vector describes what operations can be done to the
     file associated with the vnode.  The system maintains one vnode
     operations vector for each file system type configured into the kernel.
     The vnode operations vector contains a pointer to a function for each
     operation supported by the file system.  Many of the functions described
     in the vnode operations vector are closely related to their corresponding
     system calls.  In most cases, they are called as a result of the system
     call associated with the operation being invoked.

     Functions in the vnode operations vector are invoked using specialized
     macros.  The following table gives a summary of the operations.

     Macro                Description
     VOP_LOOKUP           Lookup file name in name cache
     VOP_CREATE           Create a new file
     VOP_MKNOD            Make a new device
     VOP_OPEN             Open a file
     VOP_CLOSE            Close a file
     VOP_ACCESS           Determine file accessibility
     VOP_GETATTR          Get file attributes
     VOP_SETATTR          Set file attributes
     VOP_READ             Read from a file
     VOP_WRITE            Write to a file
     VOP_FALLOCATE        Allocate backing for a file
     VOP_FDISCARD         Discard backing for a file
     VOP_IOCTL            Perform device-specific I/O
     VOP_FCNTL            Perform file control
     VOP_POLL             Test if poll event has occurred
     VOP_KQFILTER         Register a knote
     VOP_REVOKE           Eliminate vnode activity
     VOP_MMAP             Map file into user address space
     VOP_FSYNC            Flush pending data to disk
     VOP_SEEK             Test if file is seekable
     VOP_REMOVE           Remove a file
     VOP_LINK             Link a file
     VOP_RENAME           Rename a file
     VOP_MKDIR            Make a new directory
     VOP_RMDIR            Remove a directory
     VOP_SYMLINK          Create a symbolic link
     VOP_READDIR          Read directory entry
     VOP_READLINK         Read contents of a symlink
     VOP_ABORTOP          Abort pending operation
     VOP_INACTIVE         Release the inactive vnode
     VOP_RECLAIM          Reclaim vnode for another file
     VOP_LOCK             Sleep until vnode lock is free
     VOP_UNLOCK           Wake up process sleeping on lock
     VOP_ISLOCKED         Test if vnode is locked
     VOP_BMAP             Logical block number conversion
     VOP_PRINT            Print debugging information
     VOP_PATHCONF         Return POSIX pathconf data
     VOP_ADVLOCK          Advisory record locking
     VOP_WHITEOUT         Whiteout vnode
     VOP_GETPAGES         Read VM pages from file
     VOP_PUTPAGES         Write VM pages to file
     VOP_STRATEGY         Read/write a file system buffer
     VOP_BWRITE           Write a file system buffer
     VOP_GETEXTATTR       Get extended attribute
     VOP_SETEXTATTR       Set extended attribute
     VOP_LISTEXTATTR      List extended attributes
     VOP_DELETEEXTATTR    Remove extended attribute

     The implementation details of the vnode operations vector are not quite
     what is described here.

     If the file system type does not support a specific operation, it must
     nevertheless assign an appropriate stub in the vnode operations vector 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.

     Many of the functions in the vnode operations vector take a componentname
     structure.  It is used to encapsulate many parameters into a single
     function argument.  It has the following structure:

     struct componentname {
             /*
              * Arguments to lookup.
              */
             uint32_t cn_nameiop;    /* namei operation */
             uint32_t cn_flags;      /* flags to namei */
             kauth_cred_t cn_cred;   /* credentials */
             /*
              * Shared between lookup and commit routines.
              */
             const char *cn_nameptr; /* pointer to looked up name */
             size_t  cn_namelen;     /* length of looked up component */
             size_t  cn_consume;     /* chars to consume in lookup() */
     };

     The top half of the structure is used exclusively for the pathname
     lookups using VOP_LOOKUP() and is initialized by the caller.  The
     semantics of the lookup are affected by the lookup operation specified in
     cn_nameiop and the flags specified in cn_flags.  Valid operations are:

           LOOKUP  perform name lookup only
           CREATE  set up for file creation
           DELETE  set up for file deletion
           RENAME  set up for file renaming
           OPMASK  mask for operation

     Valid values for cn->cn_flags are:

           LOCKLEAF    lock inode on return
           LOCKPARENT  want parent vnode returned locked
           NOCACHE     name must not be left in name cache (see namecache(9))
           FOLLOW      follow symbolic links
           NOFOLLOW    do not follow symbolic links (pseudo)
           MODMASK     mask of operational modifiers

     No vnode operations may be called from interrupt context.  Most
     operations also require the vnode to be locked on entry.  To prevent
     deadlocks, when acquiring locks on multiple vnodes, the lock of parent
     directory must be acquired before the lock on the child directory.

     Vnode operations for a file system type generally should not be called
     directly from the kernel, but accessed indirectly through the high-level
     convenience functions discussed in vnsubr(9).

FUNCTIONS
     VOP_LOOKUP(dvp, vpp, cnp)
              Lookup a single pathname component in a given directory.  The
              argument dvp is the locked vnode of the directory to search and
              cnp is the pathname component to be searched for.  If the
              pathname component is found, the address of the resulting
              unlocked vnode is returned in vpp.  The operation specified in
              cnp->cn_nameiop indicates VOP_LOOKUP() the reason for requesting
              the lookup and uses it to cache file system type specific
              information in the vnode for subsequent operations.

              There are three types of lookups: ".", ".." (ISDOTDOT), and
              regular.  If the pathname component being searched for is ".",
              then dvp has an extra reference added to it and it is returned
              in *vpp.  For other pathname components, VOP_LOOKUP() checks the
              accessibility of the directory and searches the name cache for
              the pathname component.  See namecache(9).  If the pathname is
              not found in the name cache, the directory is searched for the
              pathname.  The resulting unlocked vnode is returned in vpp.  dvp
              is always returned locked.

              On failure *vpp is NULL, and *dvp is left locked.  If the
              operation is successful *vpp is unlocked and zero is returned.
              Typically, if *vpp and dvp are the same vnode the caller will
              need to release twice (decrement the reference count) and unlock
              once.

     VOP_CREATE(dvp, vpp, cnp, vap)
              Create a new file in a given directory.  The argument dvp is the
              locked vnode of the directory to create the new file in and cnp
              is the pathname component of the new file.  The argument vap
              specifies the attributes that the new file should be created
              with.  If the file is successfully created, the address of the
              resulting unlocked vnode is returned in vpp and zero is
              returned.

              This function is called after VOP_LOOKUP() when a file is being
              created.  Normally, VOP_LOOKUP() will have set the SAVENAME flag
              in cnp->cn_flags to keep the memory pointed to by cnp->cn_pnbuf
              valid.  If an error is detected when creating the file, this
              memory is released.  If the file is created successfully it will
              be released unless the SAVESTART flags in specified in
              cnp->cn_flags.

     VOP_MKNOD(dvp, vpp, cnp, vap)
              Make a new device-special file in a given directory.  The
              argument dvp is the locked vnode of the directory to create the
              new device-special file in and cnp is the pathname component of
              the new device-special file.  The argument vap specifies the
              attributes that the new device-special file should be created
              with.  If the file is successfully created, the address of the
              resulting unlocked vnode is returned in vpp and zero is
              returned.

              This function is called after VOP_LOOKUP() when a device-special
              file is being created.  Normally, VOP_LOOKUP() will have set the
              SAVENAME flag in cnp->cn_flags to keep the memory pointed to by
              cnp->cn_pnbuf valid.  If an error is detected when creating the
              device-special file, this memory is released.  If the device-
              special file is created successfully it will be released unless
              the SAVESTART flags in specified in cnp->cn_flags.

     VOP_OPEN(vp, mode, cred)
              Open a file.  The argument vp is the vnode of the file to open
              and mode specifies the access mode required by the calling
              process.  The calling credentials are specified by cred.  The
              access mode is a set of flags, including FREAD, FWRITE,
              O_NONBLOCK, O_APPEND, etc.  VOP_OPEN() must be called before a
              file can be accessed by a thread.  The vnode reference count is
              incremented.

              VOP_OPEN() expects the vnode vp to be locked on entry and will
              leave it locked on return.  If the operation is successful zero
              is returned, otherwise an appropriate error code is returned.

     VOP_CLOSE(vp, fflag, cred)
              Close a file.  The argument vp is the vnode of the file to close
              and fflag specifies the access mode by the calling process.  The
              possible flags are FREAD, FWRITE and FNONBLOCK.  The calling
              credentials are specified by cred.  VOP_CLOSE() frees resources
              allocated by VOP_OPEN().

              The vnode vp will be locked on entry and should remain locked on
              return.

     VOP_ACCESS(vp, mode, cred)
              Determine the accessibility (permissions) of the file against
              the specified credentials.  The argument vp is the vnode of the
              file to check, mode is the type of access required and cred
              contains the user credentials to check.  The argument mode is a
              mask which can contain VREAD, VWRITE or VEXEC.  If the file is
              accessible in the specified way, zero is returned, otherwise an
              appropriate error code is returned.

              The vnode vp will be locked on entry and should remain locked on
              return.

     VOP_GETATTR(vp, vap, cred)
              Get specific vnode attributes on a file.  The argument vp is the
              vnode of the file to get the attributes for.  The argument cred
              specifies the calling credentials.  VOP_GETATTR() uses the file
              system type specific data object vp->v_data to reference the
              underlying file attributes.  The attributes are returned in vap.
              Attributes which are not available are set to the value VNOVAL.

              For more information on vnode attributes see vattr(9).
              Historically it was considered acceptable to call VOP_GETATTR()
              without first locking the vnode.  This usage is deprecated.

              The vnode vp will be locked on entry and should remain locked on
              return.

     VOP_SETATTR(vp, vap, cred)
              Set specific vnode attributes on a file.  The argument vp is the
              locked vnode of the file to set the attributes for.  The
              argument cred specifies the calling credentials.  VOP_SETATTR()
              uses the file system type specific data object vp->v_data to
              reference the underlying file attributes.  The new attributes
              are defined in vap.  Attributes which are not being modified by
              VOP_SETATTR() should be set to the value VNOVAL.  If the
              operation is successful zero is returned, otherwise an
              appropriate error is returned.

              For more information on vnode attributes see vattr(9).

     VOP_READ(vp, uio, ioflag, cred)
              Read the contents of a file.  The argument vp is the vnode of
              the file to read from, uio is the location to read the data
              into, ioflag is a set of flags and cred are the credentials of
              the calling process.

              The ioflag argument is used to give directives and hints to the
              file system.  When attempting a read, the high 16 bits are used
              to provide a read-ahead hint (in unit of file system blocks)
              that the file system should attempt.  The low 16 bits are a bit
              mask which can contain the following flags:

                    IO_UNIT          do I/O as atomic unit
                    IO_APPEND        append write to end
                    IO_SYNC          sync I/O file integrity completion
                    IO_NODELOCKED    underlying node already locked
                    IO_NDELAY        FNDELAY flag set in file table
                    IO_DSYNC         sync I/O data integrity completion
                    IO_ALTSEMANTICS  use alternate I/O semantics
                    IO_NORMAL        operate on regular data
                    IO_EXT           operate on extended attributes
                    IO_DIRECT        do not buffer data in the kernel

              Zero is returned on success, otherwise an error is returned.
              The vnode should be locked on entry and remains locked on exit.

     VOP_WRITE(vp, uio, ioflag, cred)
              Write to a file.  The argument vp is the vnode of the file to
              write to, uio is the location of the data to write, ioflag is a
              set of flags and cred are the credentials of the calling
              process.

              The ioflag argument is used to give directives and hints to the
              file system.  The low 16 bits are a bit mask which can contain
              the same flags as VOP_READ().

              Zero is returned on success, otherwise an error is returned.
              The vnode should be locked on entry and remains locked on exit.

     VOP_FALLOCATE(vp, pos, len)
              Allocate backing store.  The argument vp is the vnode for the
              file.  The pos and len arguments (specified in bytes) name an
              extent within the file.  The blocks underlying this range,
              rounding up at the top and down at the bottom if needed, are
              checked; if no physical storage is allocated, a physical block
              is allocated and zeroed.  This operation removes "holes" from
              files.

     VOP_FDISCARD(vp, pos, len)
              Discard backing store.  The argument vp is the vnode for the
              file.  The pos and len arguments (specified in bytes) name an
              extent within the file.  The blocks underlying this range,
              rounding down at the top and up at the bottom if needed, are
              checked.  If any physical storage is used, it is deallocated.
              This operation creates "holes" in files.  Discarded blocks of
              regular files read back afterwards as zeroes.  On devices, the
              underlying discard-block operation if any (e.g. ATA TRIM) is
              issued.  The device handles this as it sees fit.  In particular
              it is not guaranteed that discarded blocks on devices will be
              zeroed; reading a discarded block might produce zeros, or ones,
              or the previously existing data, or some other data, or trash.

     VOP_IOCTL(vp, command, data, fflag, cred)
              Perform device-specific I/O.  The argument vp is the vnode of
              the file, normally representing a device.  The argument command
              specifies the device-specific operation to perform and cnp
              provides extra data for the specified operation.  The argument
              fflags is a set of flags.  The argument cred is the caller's
              credentials.  If the operation is successful, zero is returned,
              otherwise an appropriate error code is returned.

              Most file systems do not supply a function for VOP_IOCTL().
              This function implements the ioctl(2) system call.

     VOP_FCNTL(vp, command, data, fflag, cred)
              Perform file control.  The argument vp is the locked vnode of
              the file.  The argument command specifies the operation to
              perform and cnp provides extra data for the specified operation.
              The argument fflags is a set of flags.  The argument cred is the
              caller's credentials.  If the operation is successful, zero is
              returned, otherwise an appropriate error code is returned.

     VOP_POLL(vp, events)
              Test if a poll event has occurred.  The argument vp is the vnode
              of the file to poll.  It returns any events of interest as
              specified by events that may have occurred for the file.  The
              argument events is a set of flags as specified by poll(2).

              The vnode vp remains unlocked throughout the whole operation.

     VOP_KQFILTER(vp, kn)
              Register a knote kn with the vnode vn.  If the operation is
              successful zero is returned, otherwise an appropriate error code
              is returned.

              The vnode vp remains unlocked throughout the whole operation.

     VOP_REVOKE(vp, flags)
              Eliminate all activity associated with the vnode vp.  The
              argument flags is a set of flags.  If REVOKEALL is set in flags
              all vnodes aliased to the vnode vp are also eliminated.  If the
              operation is successful zero is returned, otherwise an
              appropriate error is returned.

              The vnode vp remains unlocked throughout the whole operation.

     VOP_MMAP(vp, prot, cred)
              Inform file system that vp is in the process of being memory
              mapped.  The argument prot specifies the vm access protection
              the vnode is going to be mapped with.  The argument cred is the
              caller's credentials.  If the file system allows the memory
              mapping, zero is returned, otherwise an appropriate error code
              is returned.

              Most file systems do not supply a function for VOP_MMAP() and
              use genfs_mmap() to default for success.  Only file systems
              which do not integrate with the page cache at all typically want
              to disallow memory mapping.

     VOP_FSYNC(vp, cred, flags, offlo, offhi)
              Flush pending data buffers for a file to disk.  The argument vp
              is the locked vnode of the file for flush.  The argument cred is
              the caller's credentials.  The argument flags is a set of flags.
              If FSYNC_WAIT is specified in flags, the function should wait
              for I/O to complete before returning.  The argument offlo and
              offhi specify the range of file to flush.  If the operation is
              successful zero is returned, otherwise an appropriate error code
              is returned.

              This function implements the sync(2) and fsync(2) system calls.

     VOP_SEEK(vp, oldoff, newoff, cred)
              Test if the file is seekable for the specified offset newoff.
              The argument vp is the locked vnode of the file to test.  For
              most file systems this function simply tests if newoff is valid.
              If the specified newoff is less than zero, the function returns
              error code EINVAL.

     VOP_REMOVE(dvp, vp, cnp)
              Remove a file.  The argument dvp is the locked vnode of the
              directory to remove the file from and vp is the locked vnode of
              the file to remove.  The argument cnp is the pathname component
              about the file to remove.  If the operation is successful zero
              is returned, otherwise an appropriate error code is returned.
              Both dvp and vp are locked on entry and are to be unlocked
              before returning.

     VOP_LINK(dvp, vp, cnp)
              Link to a file.  The argument dvp is the locked node of the
              directory to create the new link and vp is the vnode of the file
              to be linked.  The argument cnp is the pathname component of the
              new link.  If the operation is successful zero is returned,
              otherwise an error code is returned.  The directory vnode dvp
              should be locked on entry and will be released and unlocked on
              return.  The vnode vp should not be locked on entry and will
              remain unlocked on return.

     VOP_RENAME(fdvp, fvp, fcnp, tdvp, tvp, tcnp)
              Rename a file.  The argument fdvp is the vnode of the old parent
              directory containing in the file to be renamed and fvp is the
              vnode of the file to be renamed.  The argument fcnp is the
              pathname component about the file to be renamed.  The argument
              tdvp is the vnode of the new directory of the target file and
              tvp is the vnode of the target file (if it exists).  The
              argument tcnp is the pathname component about the file's new
              name.  If the operation is successful zero is returned,
              otherwise an error code is returned.

              The caller must hold the target file system's rename lock.  The
              source directory and file vnodes should be unlocked and their
              reference counts should be incremented before entry.  The target
              directory and file vnodes should both be locked on entry.
              VOP_RENAME() updates the reference counts prior to returning.

              Because of the complexity and nastiness of the interface, please
              do not write new code that calls VOP_RENAME() directly until
              such time as ongoing cleanup work reaches a point where the
              interface has been rendered halfway sane.

     VOP_MKDIR(dvp, vpp, cnp, vap)
              Make a new directory in a given directory.  The argument dvp is
              the locked vnode of the directory to create the new directory in
              and cnp is the pathname component of the new directory.  The
              argument vap specifies the attributes that the new directory
              should be created with.  If the file is successfully created,
              the address of the resulting unlocked vnode is returned in vpp
              and zero is returned.

              This function is called after VOP_LOOKUP() when a directory is
              being created.  Normally, VOP_LOOKUP() will have set the
              SAVENAME flag in cnp->cn_flags to keep the memory pointed to by
              cnp->cn_pnbuf valid.  If an error is detected when creating the
              directory, this memory is released.  If the directory is created
              successfully it will be released unless the SAVESTART flags in
              specified in cnp->cn_flags.

     VOP_RMDIR(dvp, vp, cnp)
              Remove a directory in a given directory.  The argument dvp is
              the locked vnode of the directory to remove the directory from
              and vp is the locked vnode of the directory to remove.  The
              argument cnp is the pathname component of the directory.  Zero
              is returned on success, otherwise an error code is returned.
              Both dvp and vp should be locked on entry and will be released
              and unlocked on return.

     VOP_SYMLINK(dvp, vpp, cnp, vap, target)
              Create a symbolic link in a given directory.  The argument dvp
              is the locked vnode of the directory to create the symbolic link
              in and cnp is the pathname component of the symbolic link.  The
              argument vap specifies the attributes that the symbolic link
              should be created with and target specifies the pathname of the
              target of the symbolic link.  If the symbolic link is
              successfully created, the address of the resulting unlocked
              vnode is returned in vpp and zero is returned.

              This function is called after VOP_LOOKUP() when a symbolic link
              is being created.  Normally, VOP_LOOKUP() will have set the
              SAVENAME flag in cnp->cn_flags to keep the memory pointed to by
              cnp->cn_pnbuf valid.  If an error is detected when creating the
              symbolic link, this memory is released.  If the symbolic link is
              created successfully it will be released unless the SAVESTART
              flags in specified in cnp->cn_flags.

     VOP_READDIR(vp, uio, cred, eofflag, cookies, ncookies)
              Read directory entry.  The argument vp is the vnode of the
              directory to read the contents of and uio is the destination
              location to read the contents into.  The argument cred is the
              caller's credentials.  The argument eofflag is the pointer to a
              flag which is set by VOP_READDIR() to indicate an end-of-file
              condition.  If eofflag is NULL, the end-of-file condition is not
              returned.  The arguments cookies and ncookies specify the
              addresses for the list and number of directory seek cookies
              generated for NFS.  Both cookies and ncookies should be NULL if
              they aren't required to be returned by VOP_READDIR().  The
              directory contents are read into struct dirent structures and
              uio->uio_offset is set to the offset of the next unread
              directory entry.  This offset may be used in a following
              invocation to continue a sequential read of the directory
              contents.  If the operation is successful zero is returned,
              otherwise an appropriate error code is returned.

              The directory should be locked on entry and will remain locked
              on return.

              In case ncookies and cookies are supplied, one cookie should be
              returned per directory entry.  The value of the cookie for each
              directory entry should be the offset within the directory where
              the on-disk version of the following directory entry starts.
              That is, for each directory entry i, the corresponding cookie
              should refer to the offset of directory entry i + 1.

              Note that the cookies array must be allocated by the callee
              using the M_TEMP malloc type as callers of VOP_READDIR() must be
              able to free the allocation.

     VOP_READLINK(vp, uio, cred)
              Read the contents of a symbolic link.  The argument vp is the
              locked vnode of the symlink and uio is the destination location
              to read the contents into.  The argument cred is the credentials
              of the caller.  If the operation is successful zero is returned,
              otherwise an error code is returned.

              The vnode should be locked on entry and will remain locked on
              return.

     VOP_ABORTOP(dvp, cnp)
              Abort pending operation on vnode dvp and free resources
              allocated in cnp.

              This operation is rarely implemented in file systems and
              genfs_abortop() is typically used instead.

     VOP_INACTIVE(vp)
              Release the inactive vnode.  VOP_INACTIVE() is called when the
              kernel is no longer using the vnode.  This may be because the
              reference count reaches zero or it may be that the file system
              is being forcibly unmounted while there are open files.  It can
              be used to reclaim space for open but deleted files.  The
              argument vp is the locked vnode to be released.  If the
              operation is successful zero is returned, otherwise an
              appropriate error code is returned.  The vnode vp must be locked
              on entry, and will remain locked on return.

     VOP_RECLAIM(vp)
              Reclaim the vnode for another file system.  VOP_RECLAIM() is
              called when a vnode is being reused for a different file system.
              Any file system specific resources associated with the vnode
              should be freed.  The argument vp is the vnode to be reclaimed.
              If the operation is successful zero is returned, otherwise an
              appropriate error code is returned.  The vnode vp should be
              locked on entry, and will be returned unlocked.

     VOP_LOCK(vp, flags)
              Sleep until vnode lock is free.  The argument vp is the vnode of
              the file to be locked.  The argument flags is LK_EXCLUSIVE to
              take the lock exclusively or LK_SHARED to take a shared lock.
              If flags contains LK_NOWAIT and the lock is busy, the operation
              will return immediately with an error code.  If flags contains
              LK_RETRY this is a hint the caller wants the lock on dead vnodes
              too.  If the operation is successful zero is returned, otherwise
              an appropriate error code is returned.  VOP_LOCK() is used to
              serialize access to the file system such as to prevent two
              writes to the same file from happening at the same time.  Kernel
              code should use vn_lock(9) to lock a vnode rather than calling
              VOP_LOCK() directly.

     VOP_UNLOCK(vp)
              Wake up process sleeping on lock.  The argument vp is the vnode
              of the file to be unlocked.  If the operation is successful zero
              is returned, otherwise an appropriate error code is returned.
              VOP_UNLOCK() is used to serialize access to the file system such
              as to prevent two writes to the same file from happening at the
              same time.

     VOP_ISLOCKED(vp)
              Test if the vnode vp is locked.  Possible return values are
              LK_EXCLUSIVE, LK_SHARED or 0 for lock held exclusively by the
              calling thread, shared lock held by anyone or unlocked,
              respectively.

              This function must never be used to make locking decisions at
              run time: it is provided only for diagnostic purposes.

     VOP_BMAP(vp, bn, vpp, bnp, runp)
              Convert the logical block number bn of a file specified by vnode
              vp to its physical block number on the disk.  The physical block
              is returned in bnp.  In case the logical block is not allocated,
              -1 is used.

              If vpp is not NULL, the vnode of the device vnode for the file
              system is returned in the address specified by vpp.  If runp is
              not NULL, the number of contiguous blocks starting from the next
              block after the queried block will be returned in runp.

     VOP_PRINT(vp)
              Print debugging information.  The argument vp is the vnode to
              print.  If the operation is successful zero is returned,
              otherwise an appropriate error code is returned.

     VOP_PATHCONF(vp, name, retval)
              Implement POSIX pathconf(2) and fpathconf(2) support.  The
              argument vp is the locked vnode to get information about.  The
              argument name specified the type of information to return.  The
              information is returned in the address specified by retval.
              Valid values for name are:

                    _PC_LINK_MAX          return the maximum number of links
                                          to a file
                    _PC_NAME_MAX          return the maximum number of bytes
                                          in a file name
                    _PC_PATH_MAX          return the maximum number of bytes
                                          in a pathname
                    _PC_PIPE_BUF          return the maximum number of bytes
                                          which will be written atomically to
                                          a pipe
                    _PC_CHOWN_RESTRICTED  return 1 if appropriate privileges
                                          are required for the chown(2) system
                                          call, otherwise zero
                    _PC_NO_TRUNC          return 0 if file names longer than
                                          {NAME_MAX} are silently truncated

              If name is recognized, *retval is set to the specified value and
              zero is returned, otherwise an appropriate error is returned.

     VOP_ADVLOCK(vp, id, op, fl, flags)
              Manipulate Advisory record locks on a vnode.  The argument vp is
              the vnode on which locks are manipulated.  The argument id is
              the id token which is changing the lock and op is the fcntl(2)
              operation to perform.  Valid values are:

                    F_SETLK  set lock
                    F_GETLK  get the first conflicted lock
                    F_UNLCK  clear lock

              The argument fl is a description of the lock.  In the case of
              SEEK_CUR, The caller should add the current file offset to
              fl->l_start beforehand.  VOP_ADVLOCK() treats SEEK_CUR as
              SEEK_SET.

              The argument flags is the set of flags.  Valid values are:

                    F_WAIT   wait until lock is granted
                    F_FLOCK  use flock(2) semantics for lock
                    F_POSIX  use POSIX semantics for lock

              If the operation is successful zero is returned, otherwise an
              appropriate error is returned.

     VOP_WHITEOUT(dvp, cnp, flags)
              Whiteout pathname component in directory with vnode dvp.  The
              argument cnp specifies the pathname component to whiteout.

              The vnode dvp should be locked on entry and will remain locked
              on return.

     VOP_GETPAGES(vp, offset, m, count, centeridx, access_type, advice, flags)
              Read VM pages from file.  The argument vp is the locked vnode to
              read the VM pages from.  The argument offset is offset in the
              file to start accessing and m is an array of VM pages.  The
              argument count points a variable that specifies the number of
              pages to read.  If the operation is successful zero is returned,
              otherwise an appropriate error code is returned.  If PGO_LOCKED
              is specified in flags, VOP_GETPAGES() might return less pages
              than requested.  In that case, the variable pointed to by count
              will be updated.

              This function is primarily used by the page-fault handing
              mechanism.

     VOP_PUTPAGES(vp, offlo, offhi, flags)
              Write modified (dirty) VM pages to file.  The argument vp is the
              vnode to write the VM pages to.  The vnode's vm object lock
              (v_uobj.vmobjlock) must be held by the caller and will be
              released upon return.  The arguments offlo and offhi specify the
              range of VM pages to write.  In case offhi is given as 0, all
              pages at and after the start offset offlo belonging the vnode vp
              will be written.  The argument flags controls the behavior of
              the routine and takes the vm pager's flags (PGO_ -prefixed).  If
              the operation is successful zero is returned, otherwise an
              appropriate error code is returned.

              The function is primarily used by the pageout handling mechanism
              and is commonly implemented indirectly by genfs_putpages() with
              the help of VOP_STRATEGY() and VOP_BMAP().

     VOP_STRATEGY(vp, bp)
              Read/write a file system buffer.  The argument vp is the vnode
              to read/write to.  The argument bp is the buffer to be read or
              written.  VOP_STRATEGY() will either read or write data to the
              file depending on the value of bp->b_flags.  If the operation is
              successful zero is returned, otherwise an appropriate error code
              is returned.

     VOP_BWRITE(vp, bp)
              Write a file system buffer.  The argument vp is the vnode to
              write to.  The argument bp specifies the buffer to be written.
              If the operation is successful zero is returned, otherwise an
              appropriate error code is returned.

     VOP_GETEXTATTR(vp, attrnamespace, name, uio, size, cred)
              Get an extended attribute.  The argument vp is the locked vnode
              of the file or directory from which to retrieve the attribute.
              The argument attrnamespace specifies the extended attribute
              namespace.  The argument name is a nul-terminated character
              string naming the attribute to retrieve.  The argument uio, if
              not NULL, specifies where the extended attribute value is to be
              written.  The argument size, if not NULL, will contain the
              number of bytes required to read all of the attribute data upon
              return.  In most cases, uio will be NULL when size is not, and
              vice versa.  The argument cred specifies the user credentials to
              use when authorizing the request.

     VOP_SETEXTATTR(vp, attrnamespace, name, uio, cred)
              Set an extended attribute.  The argument vp is the locked vnode
              of the file or directory to which to store the attribute.  The
              argument namespace specifies the extended attribute namespace.
              The argument name is a nul-terminated character string naming
              the attribute to store.  The argument uio specifies the source
              of the extended attribute data.  The argument cred specifies the
              user credentials to use when authorizing the request.

     VOP_LISTEXTATTR(vp, attrnamespace, uio, size, cred)
              Retrieve the list of extended attributes.  The argument vp is
              the locked vnode of the file or directory whose attributes are
              to be listed.  The argument attrnamespace specifies the extended
              attribute namespace.  The argument uio, if not NULL, specifies
              where the extended attribute list is to be written.  The
              argument size, if not NULL, will contain the number of bytes
              required to read all of the attribute names upon return.  In
              most cases, uio will be NULL when size is not, and vice versa.
              The argument cred specifies the user credentials to use when
              authorizing the request.

     VOP_DELETEEXTATTR(vp, attrnamespace, name, cred)
              Remove attribute name from file associated with vp.  The
              argument attrnamespace specifies the extended attribute
              namespace.  If full removal is not supported, the file system
              should return EOPNOTSUPP to allow the caller to zero out the
              value with VOP_SETEXTATTR().

              The vnode vp should be locked on entry and will remain locked on
              return.

FILES
     src/sys/kern/vnode_if.src contains the list of vnode functions, their
     definitions and an exact locking protocol.

ERRORS
     [EACCES]           Access for the specified operation is denied.

     [EDQUOT]           Quota exceeded.

     [EINVAL]           attempt to read from an illegal offset in the
                        directory; unrecognized input

     [EIO]              a read error occurred while reading the directory or
                        reading the contents of a symbolic link

     [EJUSTRETURN]      A CREATE or RENAME operation would be successful.

     [ENOATTR]          The requested attribute is not defined for this vnode.

     [ENOENT]           The component was not found in the directory.

     [ENOSPC]           The file system is full.

     [ENOTDIR]          The vnode does not represent a directory.

     [ENOTEMPTY]        attempt to remove a directory which is not empty

     [EPERM]            an attempt was made to change an immutable file

     [EROFS]            the file system is read-only

SEE ALSO
     extattr(9), intro(9), namei(9), vattr(9), vfs(9), vfsops(9), vnode(9)

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

NetBSD 10.99                     June 15, 2023                    NetBSD 10.99