VN_LOCK(9)                   OpenBSD Kernel Manual                  VN_LOCK(9)

NAME
     vn_lock - acquire the vnode lock

SYNOPSIS
     #include <sys/types.h>
     #include <sys/vnode.h>

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

DESCRIPTION
     The vn_lock() function is used to 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() function should be used.

     The flags fields may contain the following flags:

           LK_RETRY        Return the vnode even if it has been reclaimed.
           LK_INTERLOCK    Must be set if the caller owns the vnode interlock.
           LK_NOWAIT       Don't wait if the vnode lock is held by someone
                           else (may still wait on reclamation lock on or in-
                           terlock).  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.  The vn_lock() releases the vnode in-
     terlock before exit.

RETURN VALUES
     Upon successful completion, a value of 0 is returned.  Otherwise, one of
     the following errors is returned.

ERRORS
     [ENOENT]      The vnode has been reclaimed and is dead.  This error is
                   only returned if the LK_RETRY flag is not passed.

     [EBUSY]       The LK_NOWAIT flag was set and the vn_lock would have
                   slept.

SEE ALSO
     vnode(9)

BUGS
     The locking discipline is bizarre.  Many vnode operations are passed
     locked vnodes on entry but release the lock before they exit.  Discus-
     sions 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, esp. if the number of file
     systems is fewer then the number of call sites.  However, the VFS inter-
     face 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 responsibili-
     ty 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 de-
     fined.

OpenBSD 3.5                      March 9, 2001                               2
