unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

LOCKF(3)                   Library Functions Manual                   LOCKF(3)



NAME
       lockf - record locking on files

SYNOPSIS
       #include <&lt;unistd.h>&gt;

       int lockf(fd, cmd, size)
       int fd, cmd;
       long size;

DESCRIPTION
       lockf()  places,  removes, and tests for exclusive locks on sections of
       files.  These locks are either advisory or mandatory depending  on  the
       mode  bits  of  the  file.   The  lock  is mandatory if the set-GID bit
       (S_ISGID) is set and the group execute  bit  (S_IXGRP)  is  clear  (see
       stat(2V)  for  information  about  mode  bits).  Otherwise, the lock is
       advisory.

       If a process holds a mandatory exclusive lock on a segment of  a  file,
       both  read  and  write  operations block until the lock is removed (see
       WARNINGS).

       An advisory lock does not affect read and write access  to  the  locked
       segment.   Advisory locks may be used by cooperating processes checking
       for locks using F_GETLCK and voluntarily observing the  indicated  read
       and write restrictions.

       A  locking  call  on an already locked file section fails, returning an
       error value or putting the call to sleep until  that  file  section  is
       unlocked.   All  the  locks  on a process are removed when that process
       terminates.  See fcntl(2V) for more information about record locking.

       fd is an open file descriptor.  It must have O_WRONLY or O_RDWR permis-
       sion for a successful locking call.

       cmd  is  a  control  value which specifies the action to be taken.  The
       accepted values for cmd are defined in <&lt;unistd.h>&gt; as follows:

              #define   F_ULOCK   0    /* Unlock a previously locked section */
              #define   F_LOCK    1    /* Lock a section for exclusive use */
              #define   F_TLOCK   2    /* Test and lock a section (non-blocking) */
              #define   F_TEST         3    /* Test section for other process' locks */

       F_TEST returns -1 and sets errno to EACCES if a lock by another process
       already  exists  on  the  specified  section.  Otherwise, it returns 0.
       F_LOCK and F_TLOCK lock available file sections.  F_ULOCK removes locks
       from file sections.

       All other values of cmd are reserved for future applications and, until
       implemented, return an error.

       size is the number of contiguous bytes to be locked or  unlocked.   The
       resource  to  be  locked  starts  at the current offset in the file and
       extends forward size bytes if size is positive,  and  extends  backward
       size  bytes  (the  preceding  bytes up to but not including the current
       offset) if size is negative.  If size is zero,  the  section  from  the
       current offset through the largest file offset is locked (that is, from
       the current offset through the present or any  future  EOF).   An  area
       need  not  be allocated to the file to be locked, such a lock may exist
       after the EOF.

       Sections locked with F_LOCK or F_TLOCK may contain all or  part  of  an
       already  locked section.  They may also be partially or completely con-
       tained by an already locked section.  Where these overlapping or  adja-
       cent  locked  sections  occur, they are combined into a single section.
       If the table of active locks is full, a lock request requiring an addi-
       tional table entry fails and an error value is returned.

       F_LOCK  and  F_TLOCK  differ  only  in  their  response to requests for
       unavailable resources.  If a section is already locked, F_LOCK  directs
       the  calling  process to sleep until the resource is available, F_TLOCK
       directs the function to return -1 and set errno to EACCES (see ERRORS).

       When a F_ULOCK request releases part  of  a  section  with  overlapping
       locks,  the  remaining section or sections retain the lock.  If F_ULOCK
       removes the center of a locked section, the two  separate  locked  sec-
       tions  remain,  but  an  additional element is required in the table of
       active locks.  If this table is full, errno is set to  ENOLCK  and  the
       requested section is not released.

       The  danger  of  a  deadlock exists when a process controlling a locked
       resource is put to sleep by requesting  an  unavailable  resource.   To
       avoid  this  danger,  lockf() and fcntl() scan for this conflict before
       putting a locked resource to sleep.  If a  deadlock  would  result,  an
       error value is returned.

       The sleep process can be interrupted with any signal.  alarm(3V) may be
       used to provide a timeout facility where needed.

RETURN VALUES
       lockf() returns:

       0      on success.

       -1     on failure and sets errno to indicate the error.

ERRORS
       EACCES         cmd is F_TLOCK or F_TEST  and  the  section  is  already
                      locked by another process.

                      Note: In future, lockf() may generate EAGAIN under these
                      conditions, so applications testing  for  EACCES  should
                      also test for EAGAIN.

       EBADF          fd is not a valid open descriptor.

                      cmd  is  F_LOCK or F_TLOCK and the process does not have
                      write permission on the file.

       EDEADLK        cmd is F_LOCK and a deadlock would occur.

       EINTR          cmd is F_LOCK and a signal interrupted the process while
                      it was waiting to complete the lock.

       ENOLCK         cmd is F_LOCK, F_TLOCK, or F_ULOCK and there are no more
                      file lock entries available.

SEE ALSO
       chmod(2V), fcntl(2V), flock(2), fork(2V), alarm(3V), lockd(8C)

WARNINGS
       Mandatory record locks are dangerous.  If a runaway or  otherwise  out-
       of-control  process  should hold a mandatory lock on a file critical to
       the system and fail to release that lock, the entire system could  hang
       or  crash.  For this reason, mandatory record locks may be removed in a
       future SunOS release.n Use advisory record locking whenever possible.

NOTES
       A child process does not inherit locks from its parent on fork(2V).

BUGS
       lockf() locks do not interact in any way with locks granted by flock(),
       but are compatible with locks granted by fcntl().



                                21 January 1990                       LOCKF(3)