Click above to get retro games delivered to your door ever month!

Synopsis:
    #include <sys\locking.h>
    int locking( int handle, int mode, long nbyte );
    int _locking( int handle, int mode, long nbyte );

Description:
    The locking function locks or unlocks nbyte bytes of the file specified
    by handle.  Locking a region of a file prevents other processes from
    reading or writing the locked region until the region has been unlocked.
     The locking and unlocking takes place at the current file position.
     The argument mode specifies the action to be performed.  The possible
    values for mode are:

    Mode     Meaning

_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.

    With DOS, locking is supported by version 3.0 or later.  Note that
    SHARE.COM or SHARE.EXE must be installed.

    The _locking function is identical to locking.  Use _locking for
    ANSI/ISO naming conventions.

Returns:
    The locking function returns zero if successful.  Otherwise, it returns
    -1 and  errno is set to indicate the error.

Errors:
    When an error has occurred,  errno contains a value indicating the type
    of error that has been detected.

    Constant     Meaning

EACCES
    Indicates a locking violation (file already locked or unlocked).

EBADF
    Indicates an invalid file handle.

EDEADLOCK
    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.


Example:
    #include <stdio.h>
    #include <sys\locking.h>
    #include <share.h>
    #include <fcntl.h>
    #include <io.h>

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

        nbytes = 512;
        offset = 1024;
        handle = sopen( "db.fil", O_RDWR, SH_DENYNO );
        if( handle != -1 ) {
          lseek( handle, offset, SEEK_SET );
          locking( handle, LK_LOCK, nbytes );
          read( handle, buffer, nbytes );
          /* update data in the buffer */
          lseek( handle, offset, SEEK_SET );
          write( handle, buffer, nbytes );
          lseek( handle, offset, SEEK_SET );
          locking( handle, LK_UNLCK, nbytes );
          close( handle );
        }
      }

Classification:
    WATCOM

_locking conforms to ANSI/ISO naming conventions

Systems:
     locking - All

    _locking - All

See Also:
    creat, _dos_creat, _dos_open, lock, open, sopen, unlock