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: chsize() ltrunc() open() read() sopen() write()

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

Nonblocking 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/ISO 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.

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/ISO naming conventions.

See also:

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