Acquires advisory range locks on a file.
#include <nks/fsio.h>
int NXFileRangeLock (
NXHandle_t fileHandle,
unsigned long flags,
NXOffset_t offset,
NXOffset_t length);
(IN) Specifies a file handle (or descriptor), which refers to a system-maintained state description for a file.
(IN) Specifies the type of lock required. See File Range Lock Flags.
(IN) Specifies the starting offset in the file at which to set the file lock.
(IN) Specifies in bytes the length of the file lock, forward from the offset if positive, and backward from the offset if negative.
If successful, returns 0. Otherwise, returns one of the following error codes:
NXFileRangeLock acquires byte range locks on the file specified by fileHandle.
The offset parameter specifies the starting offset in the file, and this offset must not begin after the end of the file being locked. The length parameter specifies the length of the locked region.The length can extend beyond the end of the file. This allows data to be appended to the locked region in an exclusive manner, for example.
The lock requested is advisory. This means that the system does not ensure that only the lock owner is allowed to perform IO operations in a locked region. Co-operating applications are expected to perform IO operations only after successfully acquiring a byte range lock of the required type.When NX_RANGE_LOCK_TRYLOCK is not specified, the caller is blocked until the lock is available. When this flag is specified, the call returns failure immediately if the lock is not available.Overlapping byte range locks are not permitted. If the caller already owns all or part of the range attempted to be locked, the call fails. Specifically, overlapping ranges will not be merged into a single range. Also, lock ownership is tied to the file handle with which the lock was acquired and not to the file. Specifically, this means that if the same file is opened twice by a virtual machine, and a byte range lock is acquired using one handle, and the other file handle is closed, the byte range locks acquired with the open file handle are not automatically released.When NX_RANGE_LOCK_CHECK flag is also specified, a check is made to determine whether a byte range lock of the specified type can be acquired on the specified range. Either NX_RANGE_LOCK_SHARED or NX_RANGE_LOCK_EXCL must also be specified with this flag; otherwise the call will fail. Also, the NX_LOCK_TRYLOCK flag must not be specified when this flag is used. If any part of the specified range already has a byte range lock, even by the caller, the call will fail. The information returned is a snapshot at the time the call is made and can go stale any time, including as soon as the call returns.
For locking and unlocking purposes, a byte range lock's owner is fully described by the following: virtual machine, file handle, offset, and length.When a lock request is blocked, closing the file handle used for the lock request causes the lock request to return with a failure.
Closing a file handle, which has established byte range locks, results in the locks acquired using that file handle to be released automatically. Locks acquired on the same file via a different file handle are not disturbed.