[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Kernel and Subsystems, 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:
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
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. |
Related Information
The fcntl subroutine.
The flock.h file.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]