FS_FILELOCKSL - Request a file record lock/unlock
Purpose
Locks and/or unlocks a range (record) in a opened file. Version for a
64-bit file offset.
Calling Sequence
int far pascal FS_FILELOCKSL(psffsi, psffsd, pUnLockRange, pLockRange, timeout,
flags)
struct sffsi far * psffsi;
struct sffsd far * psffsd;
struct filelockl far * pUnLockRange;
struct filelockl far * pLockRange;
unsigned long timeout;
unsigned long flags;
Where
psffsi is a pointer to the file-system-independent portion of an open file
instance.
psffsd is a pointer to the file-system-dependent portion of an open file
instance.
pUnLockRange is a pointer to a filelock structure, identifying the range
of the file to be unlocked. The filelock structure has the following
format:
struct filelockl {
long long FileOffset; /* offset where the lock/unlock begins */
long long RangeLength; /* length of region locked/unlocked */
}
If RangeLength is zero, no unlocking is required.
pLockRange is a pointer to a filelock structure, identifying the range of
the file to be locked. If RangeLength is zero, no locking is required.
timeout is the maximum time in milliseconds that the requester wants to
wait for the requested ranges, if they are not immediately available.
flags is the bit mask which specifies what actions are to taken:
SHARE Bit 0 on indicates other processes can share access to this locked
range. Ranges with SHARE bit on can overlap.
SHARE Bit 0 off indicates the current process has exclusive access to the
locked range. A range with the SHARE bit off CANNOT overlap with any other
lock range.
ATOMIC Bit 1 on indicates an atomic lock request. If the lock range equals
the unlock range, an atomic lock will occur. If the ranges are not equal,
an error will be returned.
All other bits (2-31) are reserved and must be zero.
Remarks
This entry point was added to support the 32-bit DosSetFileLocks API.
If the lock and unlock range lengths are both zero, an error, ERROR_LOCK_
VIOLATION will be returned to the caller. If only a lock is desired,
pUnLockRange can be NULL or both FileOffset and RangeLength should be set
to zero when the call is made. The opposite is true for an unlock.
When the atomic bit is not set, the unlock occurs first then the lock is
performed. If an error occurs on the unlock, an error is returned and the
lock is not performed. If an error occurs on the lock, an error is
returned and the unlock remains in effect if one was requested. If the
atomic bit is set and the unlock range equals the lock range and the
unlock range has shared access but wants to change the access to exclusive
access, the function is atomic. FSDs may not support atomic lock
functions. If error ERROR_ATOMIC_LOCK_NOT_SUPPORTED is returned , the
application should do an unlock and lock the range using nonatomic
operations. The application should also be sure to refresh its internal
buffers prior to making any modifications.
Closing a file with locks still in force causes the locks to be released
in no defined order.
Terminating a process with a file open and having issued locks on that
file causes the file to be closed and the locks to be released in no
defined order.
The figure below describes the level of access granted when the accessed
region is locked. The locked regions can be anywhere in the logical file.
Locking beyond end-of-file is not an error. It is expected that the time
in which regions are locked will be short. Duplicating the handle
duplicates access to the locked regions. Access to the locked regions is
not duplicated across the DosExecPgm system call. The proper method for
using locks is not to rely on being denied read or write access, but
attempting to lock the region desired and examining the error code.
Locked Access Table
Action Exclusive Lock Shared Lock
----------------------------------------------------------------------------------
Owner read Success Success
----------------------------------------------------------------------------------
Non-owner read Return code, not block Success
----------------------------------------------------------------------------------
Owner write Success Return code, not block
----------------------------------------------------------------------------------
Non-owner write Return code, not block Return code, not block
The locked access table has the actions on the left as to whether owners
or non-owners of a file do either reads or writes of files that have
exclusive or shared locks set. A range to be locked for exclusive access
must first be cleared of any locked subranges or locked any locked
subranges or locked overlapping ranges.
Created using Inf-PHP v.2 (c) 2003 Yuri Prokushev
Created using Inf-HTML v.0.9b (c) 1995 Peter Childs