[ Previous |
Next |
Contents |
Home |
Search ]
AIX Version 4.3 Kernel and Subsystems Technical Reference, Volume 1
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
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.
The common_reclock kernel service can be
called from the process
environment only.
Return Values
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. |
Implementation Specifics
This kernel service is part of Base Operating System
(BOS) Runtime.
Related Information
The fcntl subroutine.
The flock.h file.
[ Previous |
Next |
Contents |
Home |
Search ]