VOP_LOOKUP(9) BSD 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
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 syscalls map direct-
ly 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. The lock-
ing 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 ar-
gument. 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_CREATEVOP_CREATE() creates a new directory entry for a regular file in the
directory dvp and returns a locked, referenced vnode in vpp. The file
name is in cnp and its permissions will be vap.
VOP_FSYNCVOP_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_GETEXTATTRVOP_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 integer
describing whether the attribute belongs in the user or system namespace.
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_LINKVOP_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_LOOKUPVOP_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_MKDIRVOP_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_PRINTVOP_PRINT() prints information about the vnode to the kernel message
buffer. It is not used normally, but exists only for debugging purposes.
VOP_READLINKVOP_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_REALLOCBLKSVOP_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. Currently, only
FFS implements this call.
VOP_RECLAIMVOP_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_REMOVEVOP_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 un-
locked on exit, and each has its reference count decremented by one.
VOP_REMOVE does not delete the file from disk unless its link count be-
comes zero (for file systems which support multiple links).
VOP_REVOKEVOP_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_RMDIRVOP_RMDIR() implements the rmdir(2) syscall. The directory vp will be re-
moved 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_STRATEGYVOP_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_SYMLINKVOP_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_LOCKVOP_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_WHITEOUTVOP_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 entry
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 ap-
propriate 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
description 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 de-
fault error handler, vn_default_error, to the generic description.
All lower level implementations should conform to the interfaces
described above. The rules for locking and referencing vnodes are en-
forced 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 ALSOerrno(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).
MirOS BSD #10-current March 9, 2003 3