hpux man page for lockf

lockf(2)							System Calls Manual							  lockf(2)

NAME
       lockf - provide semaphores and record locking on files

SYNOPSIS
DESCRIPTION
       The  function  allows regions of a file to be used as semaphores (advisory locks) or restricts access to only the locking process (enforce-
       ment-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 or read-write permission 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 privilege (see getprivgrp(2)), it can also use to lock files opened with read-
       only permission

       function is a control value that specifies the action to be taken.  Permissible values for function are defined in 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.

       is used to detect whether a lock by another process is present on the specified region.	returns zero if the region is accessible and if it
       is not; in which case is set to and both lock a region of a file if the region is available.  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 allocated to the file in order to be locked, because  such	locks  can
       exist past the end of the file.

       Regions	locked	with  or  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.

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

       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 error is returned, and the requested region is not released.

       Regular files with the file mode of 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 is clear, but return -1 with set
       if is set.  File access by other system functions, such as 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 or (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 and system calls (see wait(2) and pause(2)), so potential for deadlock is not eliminated.  A call or an
       call with the and flags set on a regular file returns error 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 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 signal.

       Only advisory record locking is implemented for NFS files.

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

ERRORS
       fails if any of the following occur:

	      [EACCES]	     function is or 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 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

	      [ENOLCK]	     Either  function  is  or 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 or 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 or 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.

       It is not recommended that the 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 bit of the file permissions is set.

   Application Usage
       Because	in  the  future  the  variable	will be set to rather than 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(2)