Index for Section 3

Alphabetical listing for L

Bottom of page

lockf(3)
NAME
  lockf - Lock and unlocks regions of open file descriptors

SYNOPSIS
  #include <unistd.h>

  int lockf(
	  int filedes,
	  int request,
	  off_t size );

STANDARDS
  Interfaces documented on this reference page conform to industry standards
  as follows:

  lockf(): XSH5.0

  Refer to the standards(5) reference page for more information about
  industry standards and associated tags.

PARAMETERS
  filedes
      Specifies the file to which the lock is to be applied or removed. The
      file descriptor is returned by a successful open() or fcntl() function.

  request
      Specifies one of the following constants for the lockf() function:

  F_ULOCK
      Unlocks a previously locked region in the file.

  F_LOCK
      Locks the region for exclusive use. This request causes the calling
      process to sleep if the region overlaps a locked region, and to resume
      when it is granted the lock.

  F_TLOCK
      Same as F_LOCK, except that the request returns an error if the region
      overlaps a locked region.

  F_TEST
      Tests to see if another process has already locked a region. The
      lockf() function returns 0 (zero) if the region is unlocked. If the
      region is locked, then -1 is returned and errno is set to [EACCES].

  size
      The number of bytes to be locked or unlocked for the lockf() function.
      The region starts at the current location in the open file and extends
      forward if size is positive and backward ifsize is negative. If the
      size parameter is 0 (zero), the region starts at the current location
      and extends forward to the maximum possible file size, including the
      unallocated space after the end of the file.

DESCRIPTION
  The lockf() function locks and unlocks sections of an open file. Unlike the
  fcntl() function, however, its interface is limited to setting only write
  (exclusive) locks.

  Although the lockf() and fcntl() functions are different, the
  implementations are fully integrated. Therefore, locks obtained from one
  function are honored and enforced by the other lock function.

  Each lock is either an enforced lock or an advisory lock, and must also be
  either a read lock or a write lock.

  Locks on a file are advisory or enforced depending on the mode of the file
  (see the chmod() function.) A given file can have advisory or enforced
  locks, but not both. See the sys/mode.h header file for a description of
  file attributes.

  When a process holds an enforced exclusive lock on a section of a file, no
  other process can access that section of the file with theread() or write()
  functions. In addition, the open(), truncate(), and ftruncate() functions
  cannot truncate the locked section of the file. If another process attempts
  to read or modify the locked section of the file, it sleeps until the
  section is unlocked or returns with an error indication.

  The file descriptor on which an exclusive lock is being placed must have
  been opened with write access.

  Some general rules about file locking include the following:

    ·  Changing or unlocking part of a file in the middle of a locked section
       leaves two smaller sections locked at each end of the originally
       locked section.

    ·  All locks associated with a file for a given process are removed when
       the process closes any file descriptor for that file.

    ·  Locks are not inherited by a child process after running a fork()
       function.

  Locks can start and extend beyond the current end of a file, but cannot be
  negative relative to the beginning of the file. A lock can be set to extend
  to the end of the file by setting the l_len field to 0 (zero). If a lock is
  specified with the l_start field set to 0 and the l_whence field set to
  SEEK_SET, the whole file is locked.

  Advisory file region locking is supported over NFS, provided the locking
  daemon (rpc.lockd) and status monitor daemon (rpc.statd) are running.

NOTES
  Buffered I/O does not work properly when used with file locking. Do not use
  the standard I/O package routines on files that will be locked.

  Deadlocks due to file locks in a distributed system are not always
  detected.  When such deadlocks are possible, the programs requesting the
  locks should set time-out timers.

RETURN VALUES
  Upon successful completion, a value of 0 (zero) is returned. Otherwise, a
  value of -1 is returned and errno is set to indicate the error.

ERRORS
  If the lockf() function fails, errno may be set to one of the following
  values:

  [EACCES]
      The file region is locked and F_TEST was specified; or the file region
      is locked and F_TLOCK was specified.

  [EBADF]
      The filedes parameter is not a valid open file descriptor; or the
      request parameter is F_LOCK or F_TLOCK and filedes is not a valid file
      descriptor open for writing.

  [EDEADLK]
      The lock is blocked by some lock from another process. Putting the
      calling process to sleep while waiting for that lock to become free
      would cause a deadlock.

  [EINTR]
      The request parameter is F_TLOCK and the lockf() function was
      interrupted by a signal which was caught.

  [EINVAL]
      The request parameter is not valid or size plus the current file offset
      is less than 0 (zero).

  [ENOLCK]
      The request parameter is F_LOCK, F_TLOCK, or F_UNLOCK and satisfying
      the lock or unlock request would exceed the configurable system limit
      of NLOCK_RECORD.

      [Tru64 UNIX]  If using NFS, the server is out of resources or the file
      handle is stale.

SEE ALSO
  Functions: chmod(2), close(2), exec(2), fcntl(2), flock(2), fork(2),
  open(2), read(2), write(2)

  Commands: rpc.lockd(8), rpc.statd(8)

  Standards: standards(5)

Index for Section 3

Alphabetical listing for L

Top of page