Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
lockf(2)		      System Calls Manual		      lockf(2)

       lockf - provide semaphores and record locking on	files

       The  function  allows regions of	a file to be used as semaphores	(advi-
       sory 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  be-
       comes  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 re-
       sult 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 EACCES.  and both lock a region of a
       file if the region is available.	 removes locks from a  region  of  the

       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 ex-
       tends  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 ex-
       ist past	the end	of the file.

       Regions	locked	with  or  can, in whole	or in part, contain or be con-
       tained 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 EACCES error if  the  region  is  already
       locked by another process.

       requests	can, in	whole or part, release one or more locked regions con-
       trolled by the process.	When regions are not fully released,  the  re-
       maining	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 not having the  group  execute  bit
       set,  will  have	 an  enforcement policy	enabled.  With enforcement en-
       abled, 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  re-
       source  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  EAGAIN  if
       another	process	 has locked part of the	file and the file is currently
       in enforcement mode.

       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  re-
       cover  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.

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

       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 spec-
			     ified 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.

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

       When  a file descriptor is closed, all locks on the file	from the call-
       ing 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  pro-
       vided 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 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

       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),



Want to link to this manual page? Use this URL:

home | help