vnop_lockctl Entry Point

Purpose

Sets, checks, and queries record locks.

Syntax

int vnop_lockctl (vp, offset, lckdat, cmd, retry_fn, retry_id, crp) struct vnode * vp; offset_t offset; struct eflock * lckdat; int cmd; int (* retry_fn)(); caddr_t retry_id; struct ucred * crp;

Parameters

Item	Description
vp	Points to the file's virtual node (v-node).
offset	Indicates the file offset from the open file structure. This parameter is used to establish where the lock region begins.
lckdat	Points to the elock structure. This structure describes the lock operation to perform.
cmd	Identifies the type of lock operation the vnop_lockctl entry point is to perform. It is a bit mask that takes the following lock-control values: SETFLCK If set, performs a lock set or clear. If clear, returns the lock information. The `l_type` field in the eflock structure indicates whether a lock is set or cleared. SLPFLCK If the lock is unavailable immediately, wait for it. This is only valid when the SETFLCK flag is set.
retry_fn	Points to a subroutine that is called when a lock is retried. This subroutine is not used if the lock is granted immediately. Note: If the retry_fn parameter is not a null value, the vnop_lockctl entry point will not sleep, regardless of the SLPFLCK flag.
retry_id	Points to the location where a value can be stored. This value can be used to correlate a retry operation with a specific lock or set of locks. The retry value is only used in conjunction with the retry_fn parameter. Note: This value is an opaque value and should not be used by the caller for any purpose other than a lock correlation. (This value should not be used as a pointer.)
crp	Points to the cred structure. This structure contains data that the file system can use to validate access permission.

Description

The vnop_lockctl entry point is used to request record locking. This entry point uses the information in the eflock structure to implement record locking.

If a requested lock is blocked by an existing lock, the vnop_lockctl entry point should establish a sleeping lock with the retry subroutine address (specified by the retry_fn parameter) stored in the entry point. The vnop_lockctl entry point then returns a correlating ID value to the caller (in the retry_id parameter), along with an exit value of EAGAIN. When the sleeping lock is later awakened, the retry subroutine is called with the retry_id parameter as its argument.

eflock Structure

The eflock structure is defined in the /usr/include/sys/flock.h file and includes the following fields:

Field	Description
`l_type`	Specifies type of lock. This field takes the following values: F_RDLCK Indicates read lock. F_WRLCK Indicates write lock. F_UNLCK Indicates unlock this record. A value of F_UNLCK starting at 0 until 0 for a length of 0 means unlock all locks on this file. Unlocking is done automatically when a file is closed.
`l_whence`	Specifies location that the `l_start` field offsets.
`l_start`	Specifies offset from the `l_whence` field.
`l_len`	Specifies length of record. If this field is 0, the remainder of the file is specified.
`l_vfs`	Specifies virtual file system that contains the file.
`l_sysid`	Specifies value that uniquely identifies the host for a given virtual file system. This field must be filled in before the call to the vnop_lockctl entry point.
`l_pid`	Specifies process ID (PID) of the lock owner. This field must be filled in before the call to the vnop_lockctl entry point.

Execution Environment

The vnop_lockctl entry point can be called from the process environment only.

Return Values

Item	Description
0	Indicates success.

Nonzero return values are returned from the /usr/include/sys/errno.h file to indicate failure. Valid values include:

Item	Description
EAGAIN	Indicates a blocking lock exists and the caller did not use the SLPFLCK flag to request that the operation sleep.
ERRNO	Returns an error number from the /usr/include/sys/errno.h file on failure.