
NAME
	  lockf	- record locking on files
SYNTAX
	  # include <unistd.h>
	  lockf	(fildes, function, size) long size; int	fildes,
	  function;
DESCRIPTION
	  The lockf command will allow sections	of a file to be	locked
	  (advisory write locks).  (Mandatory or enforcement mode
	  record locks are not currently available.)  Locking calls
	  from other processes which attempt to	lock the locked	file
	  section will either return an	error value or be put to sleep
	  until	the resource becomes unlocked.	All the	locks for a
	  process are removed when the process terminates.  See
	  fcntl(2) for more information	about record locking.
	  Fildes is an open file descriptor.  The file descriptor must
	  have O_WRONLY	or O_RDWR permission in	order to establish
	  lock with this function call.
	  Function is a	control	value which specifies the action to be
	  taken.  The permissible values for function are defined in
	  <unistd.h> as	follows:
	  #define   F_ULOCK   0	  /* Unlock a previously locked	section	*/
	  #define   F_LOCK    1	  /* Lock a section for	exclusive use */
	  #define   F_TLOCK   2	  /* Test and lock a section for exclusive use */
	  #define   F_TEST    3	  /* Test section for other processes locks */
	  All other values of function are reserved for	future
	  extensions and will result in	an error return	if not
	  implemented.
	  F_TEST is used to detect if a	lock by	another	process	is
	  present on the specified section.  F_LOCK and	F_TLOCK	both
	  lock a section of a file if the section is available.
	  F_UNLOCK removes locks from a	section	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
	  section from the current offset through the largest file
	  offset is locked (i.e., 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, as such locks
	  may exist past the end-of-file.
				  
	  The sections locked with F_LOCK or F_TLOCK may, in whole or
	  in part, contain or be contained by a	previously locked
	  section for the same process.	 When this occurs, or if
	  adjacent sections occur, the sections	are combined into a
	  single section.  If the request requires that	a new element
	  be added to the table	of active locks	and this table is
	  already full,	an error is returned, and the new section is
	  not locked.
	  F_LOCK and F_TLOCK requests differ only by the action	taken
	  if the resource is not available.  F_LOCK will cause the
	  calling process to sleep until the resource is available.
	  F_TLOCK will cause the function to return a -1 and set errno
	  to [EACCESS] error if	the section is already locked by
	  another process.
	  F_ULOCK requests may,	in whole or in part, release one or
	  more locked sections controlled by the process.  When
	  sections are not fully released, the remaining sections are
	  still	locked by the process.	Releasing the center section
	  of a locked section requires an additional element in	the
	  table	of active locks.  If this table	is full, an [EDEADLK]
	  error	is returned and	the requested section is not released.
	  A potential for deadlock occurs if a process controlling a
	  locked resource is put to sleep by accessing another
	  process's locked resource.  Thus calls to lock or fcntl scan
	  for a	deadlock prior to sleeping on a	locked resource.  An
	  error	return is made if sleeping on the locked resource
	  would	cause a	deadlock.
	  Sleeping on a	resource is interrupted	with any signal.  The
	  alarm(2) command may be used to provide a timeout facility
	  in applications which	require	this facility.
	  The lockf utility will fail if one or	more of	the following
	  are true:
	  [EBADF]
	       Fildes is not a valid open descriptor.
	  [EACCESS]
	       Cmd is F_TLOCK or F_TEST	and the	section	is already
	       locked by another process.
	  [EDEADLK]
	       Cmd is F_LOCK or	F_TLOCK	and a deadlock would occur.
	       Also the	cmd is either of the above or F_ULOCK and the
	       number of entries in the	lock table would exceed	the
	       number allocated	on the system.
SEE ALSO
	  alarm(2), close(2), creat(2),	fcntl(2), intro(2), open(2),
	  read(2), write(2).
     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.
     CAVEATS
	  Unexpected results may occur in processes that do buffering
	  in the user address space.  The process may later read/write
	  data which is/was locked.  The standard I/O package is the
	  most common source of	unexpected buffering.
 
