NAME
	  lockf	-  Controls open file descriptors

     SYNOPSIS
	  #include <fcntl.h>
	  #include <unistd.h>
	  int lockf(
	       int filedes,
	       int request,
	       long size );


     PARAMETERS
	  filedes   Specifies the file to which	the lock is to be
		    applied or removed.	 The file descriptor is
		    returned by	a successful open() or fcntl() func-
		    tion.

	  request   Specifies one of the following constants for the
		    lockf() function:


		    F_ULOCK   Unlocks a	previously locked region in
			      the file.

		    F_LOCK    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.

		    F_TLOCK   Same as F_LOCK, except that the request
			      returns an error if the region overlaps
			      a	locked region.

		    F_TEST    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].


	  size	    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 for-
		    ward if size is positive and backward if size 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, includ-
		    ing	the unallocated	space after the	end of the
		    file.

     DESCRIPTION
	  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 attributes.

	  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 the	read() or write() functions. In	addition, the
	  open(), truncate(), and ftruncate() functions	cannot trun-
	  cate 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:


	    o  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.

	    o  All locks associated with a file	for a given process
	       are removed when	the process closes any file descriptor
	       for that	file.

	    o  Locks are not inherited by a child process after	run-
	       ning 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.

     NOTES
	  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 pro-
	  grams	requesting the locks should set	time-out timers.

     RETURN VALUES
	  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
	  If the lockf() function fails, errno may be set to one of
	  the following	values:


	  [EACCES]  The	file region is locked, and F_TEST or F_TLOCK
		    was	specified.

	  [EINVAL]  The	request	parameter is not valid.

	  [EBADF]   The	filedes	parameter is not a valid open file
		    descriptor;	or the request parameter is F_SETLK or
		    F_SETLKW, the type of lock (l_type)	is a shared
		    lock (F_RDLCK) and filedes is not a	valid file
		    descriptor open for	reading; or the	type of	lock
		    (l_type) is	an exclusive lock (F_WRLCK) and
		    filedes is not a valid file	descriptor open	for
		    writing.

	  [EAGAIN]  The	mmap() function	is mapping a file to virtual
		    memory. See	the mmap() function.

	  [EINTR]   The	command	parameter is F_SETLKW and the lockf()
		    function was interrupted by	a signal which was
		    caught.

	  [EDEADLK] The	lock is	blocked	by some	lock from another pro-
		    cess.  Putting the calling process to sleep	while
		    waiting for	that lock to become free would cause a
		    deadlock.


	  The AT&T SVID	III reference page contains the	[ENOLCK] error
	  condition (see the attached SVID III reference page).	Should
	  I add	it?

     RELATED INFORMATION
	  Functions: chmod(2), close(2), exec(2), fcntl(2), flock(2),
	  fork(2), mmap() open(2), read(2), write(2)