lockf() -- General Function (libc)

Lock a file or a section of a file
#include <unistd.h>
int
lockf(fd, cmd, size)
int fd, cmd; long size;

The COHERENT library function lockf() allows  a process to lock part or all
of a file.  If another process  calls lockf() on the same file to request a
lock that conflicts with a previous lock, the later lockf() call returns an
error or sleeps until the file is unlocked by the first process.

fd gives a file descriptor of  an open file; the file must have been opened
with O_WRONLY or O_RDWR permission if lockf() is to succeed.

size  specifies how  many bytes  should  be locked  or unlocked.   The lock
begins  at  the  current file  position  and  extend  forward  (if size  is
positive)  or backwards  (if it  is  negative).  A  size of  zero locks  or
unlocks the entire file starting from the current position.

cmd  specifies  the action  lockf()  is to  take.   lockf() recognizes  the
following four commands, as specified in the header file <unistd.h>:

F_TEST  Test whether a lock has already been set upon the specified section
        of the file.

F_LOCK  Lock a section of the file,  if possible.  If the section cannot be
        locked, sleep until it becomes available for locking.

F_TLOCK Lock a  section of the  file, if possible.   Unlike F_LOCK, F_TLOCK
        does not sleep if the  section cannot be locked; rather, it returns
        -1 and sets errno to EAGAIN if the lock is not available.

F_ULOCK Unlock a currently existing lock.

Use lockf()  with the unbuffered I/O routines (open(),  write(), and so on)
rather  than  with  standard  I/O  library  routines  (fopen(),  fprintf(),
fwrite(), and so  on).  The buffering used by the  standard I/O library may
cause unexpected behavior with file locking.

See Also

creat(),
fcntl(),
libc,
open()

Diagnostics

lockf() returns zero  on success, -1 on failure.  On  failure, it also sets
errno to an appropriate value.  Possible errors include the following:

EINVAL  Invalid file descriptor.

EAGAIN  Requested section is already locked.

EDEADLK A deadlock  would occur  if the command  slept, or the  system lock
        table is full.

Notes

See the Lexicon entry for fcntl()  for a fuller description of the COHERENT
system's method of file locking.

© 2012 by Stephen A. Ness