VOP_LOOKUP(9) | Kernel Developer's Manual | VOP_LOOKUP(9)

# NAME

`VOP_LOOKUP`, `VOP_ABORTOP`, `VOP_ACCESS`, `VOP_ADVLOCK`, `VOP_BMAP`, `VOP_BWRITE`, `VOP_CLOSE`, `VOP_CREATE`, `VOP_FSYNC`, `VOP_GETATTR`, `VOP_INACTIVE`, `VOP_IOCTL`, `VOP_ISLOCKED`, `VOP_KQFILTER`, `VOP_LINK`, `VOP_LOCK`, `VOP_MKDIR`, `VOP_MKNOD`, `VOP_OPEN`, `VOP_PATHCONF`, `VOP_PRINT`, `VOP_READ`, `VOP_READDIR`, `VOP_READLINK`, `VOP_RECLAIM`, `VOP_REMOVE`, `VOP_RENAME`, `VOP_REVOKE`, `VOP_RMDIR`, `VOP_SETATTR`, `VOP_STRATEGY`, `VOP_SYMLINK`, `VOP_UNLOCK`, `VOP_WRITE` — vnode operations

# SYNOPSIS

`#include <sys/vnode.h>`

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

int
`VOP_ACCESS`(struct vnode *vp, int mode, struct ucred *cred, struct proc *p);

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

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

int
`VOP_BWRITE`(struct buf *bp);

int
`VOP_CLOSE`(struct vnode *vp, int fflag, struct ucred *cred, struct proc *p);

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

int
`VOP_FSYNC`(struct vnode *vp, struct ucred *cred, int waitfor, struct proc *p);

int
`VOP_GETATTR`(struct vnode *vp, struct vattr *vap, struct ucred *cred, struct proc *p);

int
`VOP_INACTIVE`(struct vnode *vp, struct proc *p);

int
`VOP_IOCTL`(struct vnode *vp, u_long command, void *data, int fflag, struct ucred *cred, struct proc *p);

int
`VOP_ISLOCKED`(struct vnode *vp);

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

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

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

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

int
`VOP_MKDIR`(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, struct ucred *cred, struct proc *p);

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

int
`VOP_PRINT`(struct vnode *vp);

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

int
`VOP_READDIR`(struct vnode *vp, struct uio *uio, struct ucred *cred, int *eofflag);

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

int
`VOP_RECLAIM`(struct vnode *vp, struct proc *p);

int
`VOP_REMOVE`(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_REVOKE`(struct vnode *vp, int flags);

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

int
`VOP_SETATTR`(struct vnode *vp, struct vattr *vap, struct ucred *cred, struct proc *p);

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

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

int
`VOP_UNLOCK`(struct vnode *vp);

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

# DESCRIPTION

The `VOP` functions implement a generic way to perform operations on vnodes. The VOP function called passes the arguments to the correct file system specific function. Not all file systems implement all operations, in which case a generic method will be used. These functions exist to provide an abstract method to invoke vnode operations without needing to know anything about the underlying file system. Many system calls map directly to a specific VOP function.

The arguments for each VOP function consist of one or more vnode pointers along with other data needed to perform the operation. Care must be taken to obey the vnode locking discipline when using VOP functions. Many VOP calls take a struct proc *p argument. This should be the current process. VOP calls are not safe to call in an interrupt context.

The vattr structure used by `VOP_CREATE`(), `VOP_GETATTR`(), `VOP_MKDIR`(), `VOP_MKNOD`(), `VOP_SETATTR`(), and `VOP_SYMLINK`() is:

    struct vattr {
    	enum vtype      va_type;      /* vnode type */
    	mode_t          va_mode;      /* files access mode and type */
    	nlink_t         va_nlink;     /* number of references */
    	uid_t           va_uid;       /* owner user id */
    	gid_t           va_gid;       /* owner group id */
    	long            va_fsid;      /* file system id */
    	u_quad_t        va_fileid;    /* file id */
    	u_quad_t        va_size;      /* file size in bytes */
    	long            va_blocksize; /* blocksize preferred for i/o */
    	struct timespec va_atime;     /* time of last access */
    	struct timespec va_mtime;     /* time of last modification */
    	struct timespec va_ctime;     /* time file changed */
    	u_long          va_gen;       /* generation number of file */
    	u_long          va_flags;     /* flags defined for file */
    	dev_t           va_rdev;      /* device the vnode represents */
    	u_quad_t        va_bytes;     /* bytes of held disk space */
    	u_quad_t        va_filerev;   /* file modification number */
    	u_int           va_vaflags;   /* operations flags */
    	long            va_spare;     /* remain quad aligned */
    };

The following sections comment on the VOP functions from the consumer's perspective.

`VOP_ABORTOP`(dvp, cnp)
  Abort any asynchronous operations pending on the vnode dvp associated with the path name cnp. This is mostly used by internal VFS code and should not be needed by file system implementors.

`VOP_ACCESS`(vp, mode, cred, p)
  Determine if the locked vnode vp can be accessed by the calling process p with credentials cred for the given access mode.

  mode may contain any of the following values:

  `VWRITE`
    check writeability
  `VREAD`
    check readability
  `VEXEC`
    check executability

  If the access check succeeds, zero is returned; otherwise, an appropriate error code is returned.

`VOP_ADVLOCK`(vp, id, op, fl, flags)
  Perform advisory locking on the vnode vp according to the operation op and lock specification fl. id identifies the resource holding the lock (typically a pointer to the holding process).

  op may be one of the following operations:

  `F_GETLK`
    Get the first lock that would block a lock request.
  `F_SETLK`
    Set a lock.
  `F_UNLCK`
    Release a lock.

  flags may contain the following flags:

  `F_WAIT`
    If required, block waiting to obtain an exclusive lock.
  `F_POSIX`
    Follow POSIX locking semantics; see fcntl(2).
  `F_FLOCK`
    Follow flock(2) locking semantics.

  Upon success, zero is returned; otherwise, an appropriate error code is returned.

`VOP_BMAP`(vp, bn, vpp, bnp, runp)
  Convert the logical block number bn of the file the locked vnode vp is associated with its physical number on-disk. The physical block number is stored in *bnp on return. vpp, if non-`NULL`, will be updated to point to the vnode of the block device of which vp is associated. runp, if non-`NULL`, will be updated to the number of contiguous disk blocks following *bnp. Upon success, zero is returned; otherwise, an appropriate error code is returned.

`VOP_BWRITE`(bp)
  Write a file system buffer to disk. Upon success, zero is returned; otherwise, an appropriate error code is returned.

`VOP_CLOSE`(vp, fflag, cred, p)
  Close the file associated with the locked vnode vp with file flags fflag by the calling process p with credentials cred. This operation should be performed only when the file is no longer being used. Upon success, zero is returned; otherwise, an appropriate error code is returned.

`VOP_CREATE`(dvp, vpp, cnp, vap)
  Create a new directory entry for a regular file in the directory dvp and return a locked, referenced vnode in vpp. The file name is in cnp and its permissions will be vap. dvp must be locked.

`VOP_FSYNC`(vp, cred, waitfor, p)
  Flush any dirty buffers associated with vp to disk. The vnode is locked on entry and exit. waitfor can be set to `MNT_WAIT` to indicate that `VOP_FSYNC`() should not return until all data is written.

`VOP_GETATTR`(vp, vap, cred, p)
`VOP_SETATTR`(vp, vap, cred, p)
  Access the vnode attributes vap of the vnode vp by the calling process p with credentials cred. `VOP_SETATTR`() requires that vp be locked. A field value for any member of vap of `VNOVAL` represents that the information could not be obtained by `VOP_GETATTR`() or should not be changed by `VOP_SETATTR`(). Upon success of obtaining or changing the attributes, zero is returned; otherwise, an appropriate error code is returned. All attributes are held in the vattr structure shown above.

`VOP_INACTIVE`(vp, p)
  Notify the underlying file system that the locked vnode vp is no longer in use. The vnode will be unlocked upon return. p specifies the calling process. This may happen when the vnode reference count reaches zero or when the underlying file system has disappeared or has been forcibly unmounted.

  Typically, the underlying file system will write any buffers associated with vp to disk or delete the file entry, if need be. The underlying file system may not necessarily release any buffers associated with vp so that it can be immediately reactivated in case the file is used again. Upon success, zero is returned; otherwise, an appropriate error code is returned.

`VOP_IOCTL`(vp, command, data, fflag, cred, p)
  Perform the control operation command with additional information data on the vnode vp, normally associated with a device, with file flags fflag by the calling process p with credentials cred. Upon success, zero is returned; otherwise, an appropriate error code is returned.

`VOP_ISLOCKED`(vp)
`VOP_LOCK`(vp, flags)
`VOP_UNLOCK`(vp)
  `VOP_LOCK`() is used internally by vn_lock(9) to lock a vnode. It should not be used by other file system code. `VOP_UNLOCK`() unlocks a vnode. Note the asymmetry between vn_lock(9) and `VOP_UNLOCK`().

  flags may contain the following flags:

  `LK_EXCLUSIVE`
    Acquire an exclusive lock.
  `LK_SHARED`
    Acquire a shared lock.
  `LK_NOWAIT`
    Don't wait if the vnode lock is held by someone else (may still wait on reclamation lock).
  `LK_RECURSEFAIL`
    Attempt at recursive lock fails.
  `LK_DRAIN`
    Used to mean something else, but is now used abused as a flag to avoid a lock inversion deadlock in deadfs. Do not use this, it must die.

  `VOP_ISLOCKED`() returns one of the following values:

  `LK_EXCLUSIVE`
    vp is locked for exclusive access by the calling thread.
  `LK_EXCLOTHER`
    vp is locked for exclusive access by a different thread.
  `LK_SHARED`
    vp is locked for shared access. The current thread may be one of the threads that have it locked.
  0
    vp is not locked.

  `VOP_ISLOCKED`() should be used cautiously, as not all file systems implement locks effectively.

`VOP_KQFILTER`(vp, kn)
  Register the knote(9) filtering information kn for the vnode vp. Only filters for `EVFILT_READ`, `EVFILT_WRITE`, and `EVFILT_VNODE` will invoke this operation. Upon success, zero is returned; otherwise, a non-zero value is returned.

`VOP_LINK`(dvp, vp, cnp)
  Increase the link count for the vnode vp. A new entry with name cnp should be added to the directory dvp. dvp is locked on entry and unlocked on exit.

`VOP_LOOKUP`(dvp, vpp, cnp)
  Find the file corresponding to the name cnp in the directory dvp and return a vnode in vpp. dvp must be locked and referenced on entry with vget(9). On a successful return, vpp will be returned locked and referenced, and dvp will return with the same reference count, but may be returned locked or unlocked depending on the specific flags used in cnp->cn_flags. On error vpp will be `NULL` and cnp->cn_flags will be set to `PDIRUNLOCK` if dvp has been unlocked.

`VOP_MKDIR`(dvp, vpp, cnp, vap)
  Create a new directory named by cnp with permissions vattr in the directory dvp. On success, the new vnode is returned locked in vpp. dvp must be locked on entry and is unlocked on exit.

`VOP_MKNOD`(dvp, vpp, cnp, vap)
  Create a device special file with name cnp and attributes vap in the directory associated with the locked vnode dvp. A pointer to the new, locked vnode will be returned in *vpp if vpp is not `NULL`. Upon success, zero is returned; otherwise, an appropriate error code is returned.

`VOP_OPEN`(vp, mode, cred, p)
  Open the file associated with the vnode vp with the access modes mode by the calling process p with credentials cred. mode takes the flags described in open(2).

  For some underlying file systems, access permissions for the file by the process are checked; for others, this is a no-op. In any case, this must be called before a process can access the file. Upon success, zero is returned; otherwise, an appropriate error code is returned.

`VOP_PATHCONF`(vp, name, retval)
  Obtain the value of the applicable POSIX configurable pathname variable (see pathconf(2)) specified by name from the locked vnode vp. The result is placed in *retval. Upon success, zero is returned; otherwise, an appropriate error code is returned.

`VOP_PRINT`(vp)
  Print information about the vnode to the kernel message buffer. It is not used normally, but exists only for debugging purposes.

`VOP_READ`(vp, uio, ioflag, cred)
  Copy data from the locked vnode vp to the buffers specified by uio with calling process credentials cred.

  ioflag may contain the following flags:

  `IO_NDELAY`
    Non-blocking I/O.
  `IO_UNIT`
    Do I/O as an atomic unit.

  Upon success, zero is returned; otherwise, an appropriate error code is returned.

`VOP_READDIR`(vp, uio, cred, eofflag)
  Read the contents of the directory associated with the locked vnode vp, usually via `VOP_READ`(), and convert its file-system-specific format to that expected by the getdents(2) system call, storing the result into the buffers specified by uio. cred specifies the credentials of the calling process. *eofflag is set to a non-zero value on return once successful end-of-file for the directory contents has been reached.

  Upon success, zero is returned; otherwise, an appropriate error code is returned.

`VOP_READLINK`(vp, uio, cred)
  Read a symbolic link and return the target's name in uio. vp is locked on entry and exit and must be a symlink.

`VOP_RECLAIM`(vp, p)
  Used by vclean(9) so that the file system has an opportunity to free memory and perform any other cleanup activity related to vp. vp is unlocked on entry and exit. `VOP_RECLAIM`() should not be used by generic code.

`VOP_REMOVE`(dvp, vp, cnp)
  Remove the link named cnp from the directory dvp. This file corresponds to the vnode vp. Both dvp and vp are locked on entry and unlocked on exit, and each has its reference count decremented by one. `VOP_REMOVE`() does not delete the file from disk unless its link count becomes zero (for file systems which support multiple links).

`VOP_RENAME`(fdvp, fvp, fcnp, tdvp, tvp, tcnp)
  Remove the link to the file with associated vnode fvp and name fcnp in the directory with associated vnode fdvp, and create a new link to the file with name tcnp (and associated locked vnode tvp, if the file already exists) residing in the directory with the associated locked vnode tdvp. fdvp, fvp, and tvp (if not `NULL`) will be released (see vrele(9)) and tdvp will have its reference count decremented (see vput(9)) on return. If not `NULL`, tvp will be unlocked on return (see vput(9)). Upon success, zero is returned; otherwise, an appropriate error code is returned.

`VOP_REVOKE`(vp, flags)
  Used by the revoke(2) system call to prevent any further access to a vnode. The vnode ops will be changed to those of deadfs, which returns only errors. vp must be unlocked.

`VOP_RMDIR`(dvp, vp, cnp)
  Remove the directory vp from the directory dvp. Both are locked on entry and unlocked on exit. The name of the directory for removal is additionally contained in cnp.

`VOP_STRATEGY`(vp, bp)
  Call the appropriate strategy function for the device vnode vp to read or write the buffer bp.

`VOP_SYMLINK`(dvp, vpp, cnp, vap, target)
  Create a symbolic link with name cnp in the directory dvp with mode vap. The link will point to target and a vnode for it is returned in vpp. The directory vnode is locked on entry and unlocked on exit. Note that unlike most VOP calls returning a vnode, `VOP_SYMLINK`() does not lock or reference vpp.

`VOP_WRITE`(vp, uio, ioflag, cred)
  Copy data from the buffers specified by uio to the locked vnode vp with calling process credentials cred.

  ioflag may contain the following flags:

  `IO_APPEND`
    Perform write at the end of file.
  `IO_NDELAY`
    Non-blocking I/O.
  `IO_SYNC`
    Wait for I/O to complete.
  `IO_UNIT`
    Do I/O as an atomic unit.

  Upon success, zero is returned; otherwise, an appropriate error code is returned.

# RETURN VALUES

The `VOP` functions return 0 to indicate success and a non-zero error code to indicate failure.

# SEE ALSO

errno(2), uiomove(9), vfs(9), vn_lock(9), vnode(9)

# AUTHORS

This man page was written by Ted Unangst for OpenBSD.

# BUGS

The locking discipline is too complex. Refer to vn_lock(9).

June 26, 2022 | Debian