VOP_LOOKUP(9)                OpenBSD Kernel Manual               VOP_LOOKUP(9)

NAME
     VOP_LOOKUP - vnode operations

SYNOPSIS
     #include <sys/vnode.h>

     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_GETEXTATTR(struct vnode *vp, int attrnamespace, const char *name,
             struct uio *uio, size_t *size, struct ucred *cred,
             struct proc *p);

     int
     VOP_ISLOCKED(struct vnode *);

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

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

     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_PRINT(struct vnode *vp);

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

     int
     VOP_REALLOCBLKS(struct vnode *vp, struct cluster_save *buflist);

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

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

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

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

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

     int
     VOP_STRATEGY(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 flags, struct proc *p);

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

DESCRIPTION
     The VOP functions implement a generic way to perform operations on vn-
     odes.  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 syscalls map di-
     rectly 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 tak-
     en to obey the vnode locking discipline when using VOP functions.  The
     locking discipline for all currently defined VOP functions is described
     in the file sys/kern/vnode_if.src.  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 following sections comment on the VOP functions from the consumer's
     perspective.  Some notes for file system implementors follow.

VOP_CREATE
     VOP_CREATE() creates a new directory entry for a regular file in the di-
     rectory dvp and returns a locked, referenced vnode in vpp.  The file name
     is in cnp and its permissions will be vap.

VOP_FSYNC
     VOP_FSYNC() flushes any dirty buffers associated with vp to disk.  The
     vnode is locked on entry and exit.  waitfor can be set to MNT_WAIT to in-
     dicate VOP_FSYNC should not return until all data is written.

VOP_GETEXTATTR
     VOP_GETEXTATTR() and VOP_SETEXTATTR() are called to get and set named ex-
     tended file attributes (see extattr(9)).  vp is the vnode for which to
     get or set the attribute.  It must be locked.  attrnamespace is an inte-
     ger describing whether the attribute belongs in the user or system names-
     pace.  name is the extended attribute to get or set.  uio is a uio(9)
     structure with the userland address containing the userland data.
     VOP_GETEXTATTR will return the actual length of the attribute in size if
     it is non-NULL.  cred is a pointer to the credentials used to access the
     file.

VOP_LINK
     VOP_LINK() increases 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
     VOP_LOOKUP() finds the file corresponding to the name cnp in the directo-
     ry dvp and returns a vnode in vpp.  dvp is locked on entry and exit, and
     vpp is locked upon a successful return.  vpp will be NULL on error, and
     cnp->cn_flags will be set to PDIRUNLOCK if dvp has been unlocked for an
     unsuccessful return.

VOP_MKDIR
     VOP_MKDIR() implements the mkdir(2) syscall.  A new directory with name
     matching that in cnp and with permissions vattr will be created 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_PRINT
     VOP_PRINT() prints information about the vnode to the kernel message
     buffer.  It is not used normally, but exists only for debugging purposes.

VOP_READLINK
     VOP_READLINK() reads a symbolic link and returns the target's name in
     uio.  vp is locked on entry and exit and must be a symlink.

VOP_REALLOCBLKS
     VOP_REALLOCBLKS() is called by the vfs write clustering code.  It gives
     the file system an opportunity to rearrange the on disk blocks for a file
     to reduce fragmentation.  vp is the locked vnode for the file, and
     buflist is a cluster of the outstanding buffers about to written.  Cur-
     rently, only FFS implements this call.

VOP_RECLAIM
     VOP_RECLAIM() is used by vclean(9) so that the file system has an oppor-
     tunity 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
     VOP_REMOVE() removes 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_REVOKE
     VOP_REVOKE() is used by the revoke(2) syscall to prevent any further ac-
     cess to a vnode.  The vnode ops will be changed to those of deadfs, which
     returns only errors.  vp must be unlocked.

VOP_RMDIR
     VOP_RMDIR() implements the rmdir(2) syscall.  The directory vp will be
     removed 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
     VOP_STRATEGY() is the only VOP call not taking a vnode argument.  It
     calls the appropriate strategy function for the device backing the
     buffer's vnode.

VOP_SYMLINK
     VOP_SYMLINK() creates 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 re-
     turned 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_LOCK
     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.
     flags should be zero in most cases.  VOP_ISLOCKED() returns 1 if vp is
     locked and 0 if not.  It should be used cautiously, as not all file sys-
     tems implement locks effectively.  Note the asymmetry between vn_lock and
     VOP_UNLOCK.

VOP_WHITEOUT
     VOP_WHITEOUT() manipulates whiteout entries in a directory.  dvp is the
     directory containing, or to contain, the whiteout.  It is locked on entry
     and exit.  cnp contains the name of the whiteout.  flags is used to indi-
     cate the operation.  Whiteouts may be created or deleted.  A whiteout en-
     try is normally used to indicate the absence of a file on a translucent
     file system.

IMPLEMENTATION NOTES
     The VOP functions are stubs which redirect their arguments to the appro-
     priate function for each file system.  In order to allow for layered file
     systems and generic bypass methods, all vnode operation implementing
     functions take only a single void * pointer as an argument.  This points
     to a structure containing the real arguments.  Additionally, this struc-
     ture contains a struct vnodeop_desc *, or vnodeop description.  The de-
     scription is typically used by the abstract VOP code, but can be useful
     to the lower implementation as well.  Every file system defines an array
     of struct vnodeopv_entry_desc that contains one entry for each implement-
     ed vnode op.  Unimplemented vnode operations match the default descrip-
     tion, vop_default_desc.  Most non-layer file systems should assign the
     default error handler, vn_default_error, to the generic description.

     All lower level implementations should conform to the interfaces de-
     scribed above.  The rules for locking and referencing vnodes are enforced
     by each file system implementation, not the VOP stubs.

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

FILES
     sys/kern/vnode_if.src  source file containing VOP definitions
     sys/kern/vnode_if.c    C file with implementations of each VOP stub call

SEE ALSO
     errno(2), 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).

OpenBSD 3.5                      March 9, 2003                               4
