unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 lockf(2)							    lockf(2)




 NAME
      lockf - provide semaphores and record locking on files

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

      int lockf(int fildes, int function, off_t size);

 DESCRIPTION
      The lockf() function allows regions of a file to be used as semaphores
      (advisory locks) or restricts access to only the locking process
      (enforcement-mode record locks).	Other processes that attempt to
      access the locked resource either return an error or sleep until the
      resource becomes unlocked.  All locks for a process are released upon
      the first close of the file, even if the process still has the file
      opened, and all locks held by a process are released when the process
      terminates.

      fildes is an open file descriptor.  The file descriptor must have been
      opened with write-only permission (O_WRONLY) or read-write permission
      (O_RDWR) in order to establish a lock with this function call (see
      open(2)).

      If the calling process is a member of a group that has the
      PRIV_LOCKRDONLY privilege (see getprivgrp(2)), it can also use lockf()
      to lock files opened with read-only permission (O_RDONLY).

      function is a control value that specifies the action to be taken.
      Permissible values for function are defined in <&lt&lt&lt;unistd.h>&gt&gt&gt; as follows:

	   #define F_ULOCK   0	    /* unlock a region */
	   #define F_LOCK    1	    /* lock a region */
	   #define F_TLOCK   2	    /* test and lock a region */
	   #define F_TEST    3	    /* test region for lock */

      All other values of function are reserved for future extensions and
      result in an error return if not implemented.

      F_TEST is used to detect whether a lock by another process is present
      on the specified region.	lockf() returns zero if the region is
      accessible and -1 if it is not; in which case errno is set to EACCES.
      F_LOCK and F_TLOCK both lock a region of a file if the region is
      available.  F_ULOCK removes locks from a region of the file.

      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 for a positive size, and backward for a negative size
      (the preceding bytes up to but not including the current offset).	 If
      size is zero, the region from the current offset through the end of
      the largest possible file is locked (that is, from the current offset
      through the present or any future end-of-file).  An area need not be



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 lockf(2)							    lockf(2)




      allocated to the file in order to be locked, because such locks can
      exist past the end of the file.

      Regions locked with F_LOCK or F_TLOCK can, in whole or in part,
      contain or be contained by a previously locked region for the same
      process.	When this occurs or if adjacent regions occur, the regions
      are combined into a single region.  If the request requires that a new
      element be added to the table of active locks but the table is already
      full, an error is returned, and the new region is not locked.

      F_LOCK and F_TLOCK requests differ only by the action taken if the
      resource is not available: F_LOCK causes the calling process to sleep
      until the resource is available, whereas F_TLOCK returns an EACCES
      error if the region is already locked by another process.

      F_ULOCK requests can, in whole or part, release one or more locked
      regions controlled by the process.  When regions are not fully
      released, the remaining regions are still locked by the process.
      Releasing the center section of a locked region requires an additional
      element in the table of active locks.  If this table is full, an
      EDEADLK error is returned, and the requested region is not released.

      Regular files with the file mode of S_ENFMT, not having the group
      execute bit set, will have an enforcement policy enabled.	 With
      enforcement enabled, reads and writes that would access a locked
      region sleep until the entire region is available if O_NDELAY is
      clear, but return -1 with errno set if O_NDELAY is set.  File access
      by other system functions, such as exec(), are not subject to the
      enforcement policy.  Locks on directories, pipes, and special files
      are advisory only; no enforcement policy is used.

      A potential for deadlock occurs if a process controlling a locked
      resource is put to sleep by accessing the locked resource of another
      process.	Thus, calls to fcntl(), lockf(), read(), or write() (see
      fcntl(2), lockf(2), read(2), and write(2)) scan for a deadlock prior
      to sleeping on a locked resource.	 Deadlock is not checked for the
      wait() and pause() system calls (see wait(2) and pause(2)), so
      potential for deadlock is not eliminated.	 A creat() call or an open()
      call with the O_CREATE and O_TRUNC flags set on a regular file returns
      error EAGAIN if another process has locked part of the file and the
      file is currently in enforcement mode.

 NETWORKING FEATURES
    NFS
      The advisory record-locking capabilities of lockf() are implemented
      throughout the network by the ``network lock daemon'' (see lockd(1M)).
      If the file server crashes and is rebooted, the lock daemon attempts
      to recover all locks associated with the crashed server.	If a lock
      cannot be reclaimed, the process that held the lock is issued a
      SIGLOST signal.




 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 lockf(2)							    lockf(2)




      Only advisory record locking is implemented for NFS files.

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

 ERRORS
      lockf() fails if any of the following occur:

	   [EACCES]	  function is F_TLOCK or F_TEST and the region is
			  already locked by another process.

	   [EBADF]	  fildes is not a valid, open file descriptor.

	   [EDEADLK]	  A deadlock would occur or the number of entries in
			  the system lock table would exceed a system-
			  dependent maximum.  HP-UX guarantees this value to
			  be at least 50.

	   [EINTR]	  A signal was caught during the lockf() system
			  call.

	   [EINVAL]	  Either function is not one of the functions
			  specified above, or size plus current offset
			  produces a negative offset into the file.

	   [EINVAL]	  size plus current offset cannot be represented
			  correctly by an object of size off_t.

	   [ENOLCK]	  Either function is F_TLOCK or F_LOCK and the file
			  is an NFS file with access bits set for
			  enforcement mode, or the file is an NFS file and a
			  system error occurred on the remote node.

 WARNINGS
      Deadlock conditions may arise when either the wait() or pause() system
      calls are used in conjunction with enforced locking (see wait(2) and
      pause(2) for details).

      When a file descriptor is closed, all locks on the file from the
      calling process are deleted, even if other file descriptors for that
      file (obtained through dup() or open(), for example) still exist.

      Unexpected results may occur in processes that use buffers in the user
      address space.  The process may later read or write data which is or
      was locked.  The standard I/O package, stdio(3S), is the most common
      source of unexpected buffering.

      In a hostile environment, locking can be misused by holding key public
      resources locked.	 This is particularly true with public read files
      that have enforcement enabled.



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 lockf(2)							    lockf(2)




      It is not recommended that the PRIV_LOCKRDONLY capability be used
      because it is provided for backward compatibility only.  This feature
      may be modified or dropped from future HP-UX releases.

      Locks default to advisory mode unless the setgid bit of the file
      permissions is set.

    Application Usage
      Because in the future the variable errno will be set to EAGAIN rather
      than EACCES when a section of a file is already locked by another
      process, portable application programs should expect and test for
      either value.  For example:

	   if (lockf(fd, F_TLOCK, siz) == -1)
	       if ((errno == EAGAIN) || (errno == EACCES))
	       /*
	       * section locked by another process
	       * check for either EAGAIN or EACCES
	       * due to different implementations
	       */
	       else if ...
	       /*
	       * check for other errors
	       */

 SEE ALSO
      lockd(1M), statd(1M), chmod(2), close(2), creat(2), fcntl(2),
      creat64(2), open(2), pause(2), read(2), stat(2), wait(2), write(2),
      unistd(5).

 STANDARDS CONFORMANCE
      lockf(): SVID2, SVID3, XPG2






















 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000