common_reclock Kernel Service

Purpose

Implements a generic interface to the record locking functions.

Syntax

#include <sys/types.h>
#include <sys/flock.h>

common_reclock( gp, size, offset, 
lckdat, cmd, retray_fcn, retry_id, lock_fcn, 
rele_fcn)
struct gnode *gp;
offset_t size;
offset_t offset;
struct eflock *lckdat;
int cmd;
int (*retry_fcn)();
ulong *retry_id;
int (*lock_fcn)();
int (*rele_fcn)();

Parameters

Item	Description
gp	Points to the gnode that represents the file to lock.
size	Identifies the current size of the file in bytes.
offset	Specifies the current file offset. The system uses the offset parameter to establish where the lock region is to begin.
lckdat	Points to an eflock structure that describes the lock operation to perform.
cmd	Defines the type of operation the kernel service performs. This parameter is a bit mask consisting of the following bits: SETFLCK If set, the system sets or clears a lock. If not set, the lock information is returned. SLPFLCK If the lock cannot be granted immediately, wait for it. This is only valid when SETFLCK flag is set. INOFLCK The caller is holding a lock on the object referred to by the gnode. The common_reclock kernel service calls the release function before sleeping, and the lock function on return from sleep. When the cmd parameter is set to SLPFLCK, it indicates that if the lock cannot be granted immediately, the service should wait for it. If the retry_fcn parameter contains a valid pointer, the common_reclock kernel service does not sleep, regardless of the SLPFLCK flag.
retry_fcn	Points to a retry function. This function is called when the lock is retried. The retry function is not used if the lock is granted immediately. When the requested lock is blocked by an existing lock, a sleeping lock is established with the retry function address stored in it. The common_reclock kernel service then returns a correlating ID (see the retry_id parameter) to the calling routine, along with an exit value of EAGAIN. When the sleeping lock is awakened, the retry function is called with the correlating ID as its ID argument. If this argument is not NULL, then the common_ reclock kernel service does not sleep, regardless of the SLPFLCK command flag.
retry_id	Points to location to store the correlating ID. This ID is used to correlate a retry operation with a specific lock or set of locks. This parameter is used only in conjunction with retry function. The value stored in this location is an opaque value. The caller should not use this value for any purpose other than lock correlation.
lock_fcn	Points to a lock function. This function is invoked by the common_ reclock kernel service to lock a data structure used by the caller. Typically this is the data structure containing the gnode to lock. This function is necessary to serialize access to the object to lock. When the common_reclock kernel service invokes the lock function, it is passed the private data pointer from the gnode as its only argument.
rele_fcn	Points to a release function. This function releases the lock acquired with the lock function. When the release function is invoked, it is passed the private data pointer from the gnode as its only argument.

Description

The common_reclock routine implements a generic interface to the record-locking functions. This service allows distributed file systems to use byte-range locking. The kernel service does the following when a requested lock is blocked by an existing lock:

Establishes a sleeping lock with the retry function in the lock structure. The address of the retry function is specified by the retry_fcn parameter.
Returns a correlating ID value to the caller along with an exit value of EAGAIN. The ID is stored in the retry_id parameter.
Calls the retry function when the sleeping lock is later awakened, the retry function is called with the retry_id parameter as its argument.
Note: Before a call to the common_ reclock subroutine, the eflock structure must be completely filled in. The lckdat parameter points to the eflock structure.

The caller can hold a serialization lock on the data object pointed to by the gnode. However, if the caller expects to sleep for a blocking-file lock and is holding the object lock, the caller must specify a lock function with the lock_fcn parameter and a release function with the rele_fcn parameter.

The lock is described by a eflock structure. This structure is identified by the lckdat parameter. If a read lock (F_RDLCK) or write lock (F_WRLCK ) is set with a length of 0, the entire file is locked. Similarly, if unlock (F_UNLCK) is set starting at 0 for 0 length, all locks on this file are unlocked. This method is how locks are removed when a file is closed.

To allow the common_reclock kernel service to update the per-gnode lock list, the service takes a GN_RECLK_LOCK lock during processing.

Execution Environment

The common_reclock kernel service can be called from the process environment only.

Return Values

Item	Description
0	Indicates successful completion.
EAGAIN	Indicates a lock cannot be granted because of a blocking lock and the caller did not request that the operation sleep.
ERRNO	Indicates an error. Refer to the fcntl system call for the list of possible values.