DosSetFileLocks()--Lock and Unlock a Byte Range of an Open File

 #define INCL_DOSERRORS
 #define INCL_DOSFILEMGR
 #include <os2.h>

  APIRET APIENTRY DosSetFileLocks(HFILE FileHandle,
                   PFILELOCK ppUnLockRange,
                   PFILELOCK ppLockRange,
                   ULONG ulTimeOut,
                   ULONG ulFlags);  

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.

Usage Notes

1. 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.
   
   
2. 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
   
   
3. 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
   
   
4. 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
   
   
5. 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.
   
   
6. Locks placed on character special files result in advisory locks.  For more information on 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

See Code disclaimer information for information pertaining to code examples.

The following example opens, locks, and unlocks a file.

#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);
}