DosSetFileLocks()--Lock and Unlock a Byte Range of an Open File
Syntax
#define INCL_DOSERRORS #define INCL_DOSFILEMGR #include <os2.h> APIRET APIENTRY DosSetFileLocks(HFILE FileHandle, PFILELOCK ppUnLockRange, PFILELOCK ppLockRange, ULONG ulTimeOut, ULONG ulFlags);Service Program Name: QP0LLIB1
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes.
The DosSetFileLocks() function locks and unlocks a range of an open file. A non-zero range indicates that a lock or unlock request is being made.
Parameters
- FileHandle
- (Input) The file descriptor of the file in which a range is to be locked.
- ppUnlockRange
- (Input) Address of the structure containing the offset and length of a
range to be unlocked. The structure is as follows:
- FileOffset
- The offset to the beginning of the range to be unlocked.
- RangeLength
- The length of the range to be unlocked. A value of zero means that unlocking is not required.
- ppLockRange
- (Input) Address of the structure containing the offset and length of a
range to be locked. The structure is as follows:
- FileOffset
- The offset to the beginning of the range to be locked.
- RangeLength
- The length of the range to be locked. A value of zero means that locking is not required.
- ulTimeOut
- (Input) The maximum time, in milliseconds, that the process is to wait for the requested locks.
- ulFlags
- (Input) Flags that describe the action to be taken. If any flags other than
those listed below are specified, the error ERROR_INVALID_PARAMETER will be
returned.
The following values are to be specified in ulFlags:
- '0x0002' or QP0L_DOSSETFILELOCKS_ATOMIC
- Atomic. This bit defines a request for atomic locking. If this bit is set to 1 and the lock range is equal to the unlock range, an atomic lock occurs. If this bit is set to 1 and the lock range is not equal to the unlock range, ERROR_LOCK_VIOLATION is returned.
- '0x0001' or QP0L_DOSSETFILELOCKS_SHARE
- Share. This bit defines the type of access that other processes may have to
the file range that is being locked.
If this bit is set to 0 (the default), other processes have no access to the locked file range. The current process has exclusive access to the locked file range, which must not overlap any other locked file range.
If this bit is set to 1, the current process and other processes have shared access to the locked file range. A file range with shared access may overlap any other file range with shared access, but must not overlap any other file range with exclusive access.
Authorities
No authorization is required.
Return Value
- NO_ERROR (0)
- DosSetFileLocks() was successful.
- value (non-zero)
- DosSetFileLocks() was not successful. The value that is returned indicates the error.
Error Conditions
If DosSetFileLocks() is not successful, the value that is returned is one of the following errors. The <bseerr.h> header file defines these values.
- [ERROR_GEN_FAILURE]
-
A general failure occurred.
This may result from damage in the system. Refer to messages in the job log for other possible causes.
- [ERROR_INVALID_HANDLE]
-
An invalid file handle was found.
The file handle passed to this function is not valid.
- [ERROR_LOCK_VIOLATION]
-
A lock violation was found.
The requested lock and unlock ranges are both zero.
- [ERROR_INVALID_PARAMETER]
-
An invalid parameter was found.
A parameter passed to this function is not valid.
The byte range specified by the offset and length in the ppUnlockRange or ppLockRange parameters extends beyond 2GB minus 1 byte.
- [ERROR_ATOMIC_LOCK_NOT_SUPPORTED]
-
The atomic lock operation is not supported.
The file system does not support atomic lock operations.
- [ERROR_TIMER_NOT_SUPPORTED]
-
The lock timer value is not supported.
The file system does not support the lock timer value.
Error Messages
The system may send the following messages from this function.
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPFA0D4 E | File system error occurred. Error number &1. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
Usage Notes
- If this function is called
by a thread executing one of the scan-related exit programs (or any of its
created threads), it will fail with error code [ENOTSUP]. See Integrated File System Scan on Open Exit Programs and Integrated File System Scan on Close Exit Programs
for more information.
- This function will fail with error code [ERROR_GEN_FAILURE] when all the
following conditions are true:
- Where multiple threads exist in the job.
- The object this function is operating on resides in a file system that is
not threadsafe. Only the following file systems are threadsafe for this
function:
- "Root" (/)
- QOpenSys
- User-defined
- QNTC
- QSYS.LIB
- Independent ASP QSYS.LIB
- QOPT
- QFileSvr.400
- The following file systems do not support timer values other than 0. An
attempt to a value other than 0 for the timer value results in an
ERROR_TIMER_NOT_SUPPORTED error.
Also, the following file systems do not support the atomic locking flag. If you turn on the atomic locking flag, an ERROR_ATOMIC_LOCKS_NOT_SUPPORTED error is returned.
- "Root" (/)
- QOpenSys
- User-Defined File System
- QDLS
- QOPT
- QNetWare
- The following file systems do not support byte range locks. An attempt to
use this API results in an ERROR_GEN_FAILURE error.
- QSYS.LIB
- Independent ASP QSYS.LIB
- Network File System
- QFileSvr.400
- When you develop in C-based languages and this function is compiled with
the _LARGE_FILES macro defined, it will be mapped to
DosSetFileLocks64(). Additionally, the PFILELOCK data
type will be mapped to a type PFILELOCK64.
- Locks placed on character special files result in advisory locks. For more information about advisory locking, please see the fcntl()--Perform File Control Command.
Related Information
- The <fcntl.h> file (see Header Files for UNIX®-Type Functions)
- The <os2.h> file (see Header Files for UNIX-Type Functions)
- The <os2def.h> file (see Header Files for UNIX-Type Functions)
- The <bse.h> file (see Header Files for UNIX-Type Functions)
- The <bsedos.h> file (see Header Files for UNIX-Type Functions)
- The <bseerr.h> file (see Header Files for UNIX-Type Functions)
- DosSetFileLocks64()--Lock and Unlock a Byte Range of an Open File (Large File Enabled)
Example
The following example opens, locks, and unlocks a file.
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#define INCL_DOSERRORS #define INCL_DOSFILEMGR #include <os2.h> #include <stdio.h> #define NULL_RANGE 0L #define LOCK_FLAGS 0 main() { char fn[]="lock.file"; char buf[] = "Test data for locking and unlocking range of a file"; int fd; ULONG lockTimeout = 2000; /* lock timeout of 2 seconds */ FILELOCK Area; /* area of file to lock/unlock */ Area.Offset = 4; /* start locking at byte 4 */ Area.Range = 10; /* lock 10 bytes for the file */ /* Create a file for this example */ fd = creat(fn, S_IWUSR | S_IRUSR); /* Write some data to the file */ write(fd, buf, sizof(buf) -1); close(fd); /* Open the file */ if ((fd = open(fn, O_RDWR) < 0) { perror("open() error"); return; } /* Lock a range */ rc = DosSetFileLocks((HFILE)fd, NULL_RANGE, &Area, &LockTimeout, LOCK_FLAGS); if(rc != 0) /* Lock failed */ { perror("DosSetFileLocks() error"); } /* Unlock a range */ rc = DosSetFileLocks((HFILE)fd, &Area, NULL_RANGE, &LockTimeout, LOCK_FLAGS); if(rc != 0) /* Unlock failed */ { perror("DosSetFileLocks() error"); } close(fd); unlink(fn); }
API introduced: V4R2