*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> lockf (3)              



NAME    [Toc]    [Back]

       lockf - Lock and unlocks regions of open file descriptors

SYNOPSIS    [Toc]    [Back]

       #include <unistd.h>

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

STANDARDS    [Toc]    [Back]

       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    [Toc]    [Back]

       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.  Specifies one of the following
 constants for the lockf() function: Unlocks  a  previously
  locked  region  in  the file.  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.   Same  as  F_LOCK,
       except  that  the  request  returns an error if the region
       overlaps a locked region.  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].
       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    [Toc]    [Back]

       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

       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    [Toc]    [Back]

       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

RETURN VALUES    [Toc]    [Back]

       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    [Toc]    [Back]

       If the lockf() function fails, errno may be set to one  of
       the following values: The file region is locked and F_TEST
       was specified; or the file region is  locked  and  F_TLOCK
       was  specified.  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.  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.   The  request  parameter  is  F_TLOCK  and  the
       lockf() function was interrupted by  a  signal  which  was
       caught.   The  request parameter is not valid or size plus
       the current file  offset  is  less  than  0  (zero).   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    [Toc]    [Back]

       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)

[ Back ]
 Similar pages
Name OS Title
dup Tru64 Control open file descriptors
dup2 Tru64 Control open file descriptors
fcntl Tru64 Control open file descriptors
flock OpenBSD apply or remove an advisory lock on an open file
flock Tru64 Apply or remove an advisory lock on an open file
flock Linux apply or remove an advisory lock on an open file
flock IRIX apply or remove an advisory lock on an open file
flock FreeBSD apply or remove an advisory lock on an open file
flock NetBSD apply or remove an advisory lock on an open file
lockf Linux apply, test or remove a POSIX lock on an open file
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service