unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



flock(2)							     flock(2)



NAME
  flock	- Applies or removes an	advisory lock on an open file

SYNOPSIS

  #include <&lt;sys/fcntl.h>&gt;

  int flock(
	  int filedes,
	  int operation	);

PARAMETERS

  filedes   Specifies a	file descriptor	returned by a successful open()	or
	    fcntl() function, identifying the file to which the	lock is	to be
	    applied or removed.

  operation Specifies one of the following constants for flock(), defined in
	    the	fcntl.h	file:

	    LOCK_SH   Apply a shared lock.

	    LOCK_EX   Apply an exclusive lock.

	    LOCK_NB   Do not block when	locking. This value can	be logically
		      ORed with	either LOCK_SH or LOCK_EX.

	    LOCK_UN   Remove a lock.

DESCRIPTION

  The flock() function applies or removes an advisory lock on the file asso-
  ciated with the filedes file descriptor.  Advisory locks allow cooperating
  processes to perform consistent operations on	files, but do not guarantee
  consistency (that is,	processes may still access files without using
  advisory locks, possibly resulting in	inconsistencies).

  You can use the flock() function to coordinate a file's lock status on
  local, CFS, and NFS file systems.

  The locking mechanism	allows two types of locks: shared locks	and exclusive
  locks.  At any time multiple shared locks may	be applied to a	file, but at
  no time are multiple exclusive, or both shared and exclusive,	locks allowed
  simultaneously on a file.

  A shared lock	may be upgraded	to an exclusive	lock, and vice versa, simply
  by specifying	the appropriate	lock type.  This results in the	previous lock
  being	released and the new lock applied (possibly after other	processes
  have gained and released the lock).

  Requesting a lock on an object that is already locked	normally causes	the
  caller to be blocked until the lock may be acquired.	If LOCK_NB is
  included in operation, then this will	not happen; instead, the call will
  fail and errno will be set to	[EWOULDBLOCK].

NOTES

  Locks	are on files, not file descriptors.  That is, file descriptors dupli-
  cated	using the dup()	or fork() functions do not result in multiple
  instances of a lock, but rather multiple references to a single lock.	 If a
  process holding a lock on a file forks and the child explicitly unlocks the
  file,	the parent will	lose its lock.

  Processes blocked awaiting a lock may	be awakened by signals.

  The flock() interface	is not part of any UNIX	standard.  Therefore, if you
  are designing	and writing applications to be portable	across platforms, you
  should use the fcntl() file locking interface	instead	of flock().

RETURN VALUES

  Upon successful completion, 0	(zero) is returned.  Otherwise,	-1 is
  returned and errno is	set to indicate	the error.

ERRORS

  If the flock() function fails, errno may be set to one of the	following
  values:

  [EWOULDBLOCK]
	    The	file is	locked and the LOCK_NB option was specified.

  [EBADF]   The	filedes	argument is not	a valid	open file descriptor.

  [EINTR]   A signal interrupted the flock call.

  [EINVAL]  The	operator is not	valid.

  [ENOLCK]  The	lock table is full.  Too many regions are already locked.

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

RELATED	INFORMATION

  Functions: close(2), exec(2),	fcntl(2), fork(2), open(2), lockf(3)