locking, _locking

lock or unlock part of a file

Synopsis:

#include <sys/locking.h>
int locking( int filedes , int mode, long nbyte );
int _locking( int filedes , int mode, long nbyte );

Description:

The locking() function locks or unlocks nbyte bytes of the file specified by filedes. The file must be opened with write access to lock it.

Locking is a protocol designed for updating a file shared among concurrently running applications. Locks are only advisory, that is, they don't prevent an errant or poorly-designed application from overwriting a locked region of a shared file. An application should use locks to indicate regions of a file that are to be updated by the application, and it should respect the locks of other applications.

Locks are ignored by the following functions:

The locking and unlocking takes place at the current file position. The argument mode specifies the action to be performed. The possible values are:

_LK_LOCK, LK_LOCK
Locks the specified region. The function will retry to lock the region after 1 second intervals until successful or until 10 attempts have been made.
_LK_RLCK, LK_RLCK
Same action as _LK_LOCK.
_LK_NBLCK, LK_NBLCK
Non-blocking lock: makes only 1 attempt to lock the specified region.
_LK_NBRLCK, LK_NBRLCK
Same action as _LK_NBLCK.
_LK_UNLCK, LK_UNLCK
Unlocks the specified region. The region must have been previously locked.

Multiple regions of a file can be locked, but no overlapping regions are allowed. You cannot unlock multiple regions in the same call, even if the regions are contiguous. All locked regions of a file should be unlocked before closing a file or exiting the program.

The _locking() function is identical to locking(). Use _locking() for ANSI naming conventions.

Returns:

0
Success
(-1)
An error occurred. errno is set to indicate the error.

Errors:

EACCES
Indicates a locking violation (file already locked or unlocked).
EBADF
Indicates an invalid file descriptor.
EDEADLK
Indicates a locking violation. This error is returned when mode is LK_LOCK or LK_RLCK, and the file cannot be locked after 10 attempts.
EINVAL
Indicates that an invalid argument was given to the function.

See also:

creat(), errno, fcntl(), lock(), open(), sopen(), unlock()

Examples:

#include <stdio.h>
#include <sys/locking.h>
#include <share.h>
#include <fcntl.h>
#include <unistd.h>

void main()
  {
    int filedes ;
    unsigned nbytes;
    unsigned long offset;
    char buffer[512];

    nbytes = 512;
    offset = 1024;
    filedes = sopen( "db.fil", O_RDWR, SH_DENYNO );
    if( filedes != -1 ) {
      lseek( filedes , offset, SEEK_SET );
      locking( filedes , LK_LOCK, nbytes );
      read( filedes , buffer, nbytes );

      /* update data in the buffer */

      lseek( filedes , offset, SEEK_SET );
      write( filedes , buffer, nbytes );
      lseek( filedes , offset, SEEK_SET );
      locking( filedes , LK_UNLCK, nbytes );
      close( filedes );
    }
  }

Classification:

WATCOM

_locking() conforms to ANSI naming conventions.

Systems:

All (except Netware, DOS/PM)