VNSUBR(9) OpenBSD Kernel Manual VNSUBR(9)NAME
vnsubr, vn_close, vn_default_error, vn_isunder, vn_lock, vn_marktext,
vn_rdwr, vn_open, vn_stat, vn_writechk - high-level convenience functions
for vnode operations
SYNOPSIS
#include <sys/param.h>
#include <sys/lock.h>
#include <sys/vnode.h>
int
vn_close(struct vnode *vp, int flags, struct ucred *cred, struct proc
*p);
int
vn_default_error(void *v);
int
vn_isunder(struct vnode *dvp, struct vnode *rvp, struct proc *p);
int
vn_lock(struct vnode *vp, int flags, struct proc *p);
void
vn_marktext(struct vnode *vp);
int
vn_open(struct nameidata *ndp, int fmode, int cmode);
int
vn_rdwr(enum uio_rw rw, struct vnode *vp, caddr_t base, int len, off_t
offset, enum uio_seg segflg, int ioflg, struct ucred *cred, size_t
*aresid, struct proc *p);
int
vn_stat(struct vnode *vp, struct stat *sb, struct proc *p);
int
vn_writechk(struct vnode *vp);
DESCRIPTION
The high-level functions described in this page are convenience functions
for simplified access to the vnode operations described in VOP_LOOKUP(9).
vn_close(vp, flags, cred, p)
Common code for a vnode close. The argument vp is the unlocked
vnode of the vnode to close. vn_close() simply locks the vnode,
invokes the vnode operation VOP_CLOSE() and calls vput(9) to
return the vnode to the freelist or holdlist. Note that
vn_close() expects an unlocked, referenced vnode and will
dereference the vnode prior to returning. If the operation is
successful, zero is returned; otherwise an appropriate error is
returned.
vn_default_error(v)
A generic "default" routine that just returns error. It is used
by a file system to specify unsupported operations in the vnode
operations vector.
vn_isunder(dvp, rvp, p)
Common code to check if one directory specified by the vnode rvp
can be found inside the directory specified by the vnode dvp.
The argument p is the calling process. vn_isunder() is intended
to be used in chroot(2), chdir(2), fchdir(2), etc., to ensure
that chroot(2) actually means something. If the operation is
successful, zero is returned; otherwise 1 is returned.
vn_lock(vp, flags, p)
Acquire the vnode lock. Certain file system operations require
that the vnode lock be held when they are called. See
sys/kern/vnode_if.src for more details.
The vn_lock() function must not be called when the vnode's
reference count is zero. Instead, the vget(9) function should be
used.
The flags argument may contain the following flags:
LK_RETRY Return the vnode even if it has been
reclaimed.
LK_NOWAIT Don't wait if the vnode lock is held by
someone else (may still wait on reclamation
lock). Must not be used with LK_RETRY.
LK_EXCLUSIVE Acquire an exclusive lock.
LK_SHARED Acquire a shared lock.
The vn_lock() function can sleep.
vn_marktext(vp)
Common code to mark the vnode vp as being the text of a running
process.
vn_open(ndp, fmode, cmode)
Common code for vnode open operations. The pathname is described
in the nameidata pointer (see namei(9)). The arguments fmode and
cmode specify the open(2) file mode and the access permissions
for creation. vn_open() checks permissions and invokes the
VOP_OPEN(9) or VOP_CREATE(9) vnode operations. If the operation
is successful, zero is returned; otherwise an appropriate error
code is returned.
vn_rdwr(rw, vp, base, len, offset, segflg, ioflg, cred, aresid, p)
Common code to package up an I/O request on a vnode into a uio
and then perform the I/O. The argument rw specifies whether the
I/O is a read (UIO_READ) or write (UIO_WRITE) operation. The
unlocked vnode is specified by vp. The arguments p and cred are
the calling process and its credentials. The remaining arguments
specify the uio parameters. For further information on these
parameters, see uiomove(9).
vn_stat(vp, sb, p)
Common code for a vnode stat operation. The vnode is specified
by the argument vp, and sb is the buffer in which to store the
stat information. The argument p is the calling process.
vn_stat() basically calls the vnode operation VOP_GETATTR(9) and
transfers the contents of a vattr structure into a struct stat.
If the operation is successful, zero is returned; otherwise an
appropriate error code is returned.
vn_writechk(vp)
Common code to check for write permission on the vnode vp. A
vnode is read-only if it is in use as a process's text image. If
the vnode is read-only, ETXTBSY is returned; otherwise zero is
returned to indicate that the vnode can be written to.
ERRORS
[ETXTBSY] Cannot write to a vnode since it is a process's text image.
[ENOENT] The vnode has been reclaimed and is dead. This error is
only returned if the LK_RETRY flag is not passed to
vn_lock().
[EBUSY] The LK_NOWAIT flag was set and vn_lock() would have slept.
CODE REFERENCES
This section describes places within the OpenBSD source tree where actual
code implementing or using the vnode framework can be found. All
pathnames are relative to /usr/src.
The high-level convenience functions are implemented within the files
sys/kern/vfs_vnops.c and sys/sys/vnode.h.
SEE ALSOfile(9), lock(9), namei(9), vfs(9), vnode(9), VOP_LOOKUP(9)BUGS
The locking discipline is bizarre. Many vnode operations are passed
locked vnodes on entry but release the lock before they exit.
Discussions with Kirk McKusick indicate that locking discipline evolved
out of the pre-VFS way of doing inode locking. In addition, the current
locking discipline may actually save lines of code, especially if the
number of file systems is fewer than the number of call sites. However,
the VFS interface would require less wizardry if the locking discipline
were simpler.
The locking discipline is used in some places to attempt to make a series
of operations atomic (e.g., permissions check + operation). This does
not work for non-local file systems that do not support locking (e.g.,
NFS).
Are vnode locks even necessary? The security checks can be moved into
the individual file systems. Each file system can have the
responsibility of ensuring that vnode operations are suitably atomic.
The LK_NOWAIT flag does prevent the caller from sleeping.
The locking discipline as it relates to shared locks has yet to be
defined.
OpenBSD 4.9 March 18, 2009 OpenBSD 4.9
