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

FreeBSD Manual Pages

  
 
  

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

NAME
       fcntl - file control

SYNOPSIS
   Remarks
       The  ANSI  C "" construct denotes a variable length argument list whose
       optional	[or required] members are given	in the associated comment

DESCRIPTION
       provides	for control over open files.  fildes is	an open	file  descrip-
       tor.

       The following are possible values for the cmd argument:

	      Return  a	 new file descriptor having the	following characteris-
	      tics:

				  o  Lowest numbered available file descriptor
				     greater  than or equal to the third argu-
				     ment, arg,	taken as an integer of type

				  o  Same open file (or	pipe) as the  original
				     file.

				  o  Same  file	 pointer  as the original file
				     (that is, both file descriptors share one
				     file pointer).

				  o  Same   access   mode   (read,   write  or
				     read/write).

				  o  Same file status  flags  (that  is,  both
				     file descriptors share the	same file sta-
				     tus flags).

				  o  The close-on-exec	flag  associated  with
				     the  new file descriptor is set to	remain
				     open across exec(2) system	calls.

	      Get the close-on-exec flag associated with the file descriptor
			     fildes.  If the low-order bit is  the  file  will
			     remain  open  across  exec(2), otherwise the file
			     will be closed upon execution of exec(2).

	      Set the close-on-exec flag associated with
			     fildes to the low-order bit of  the  third	 argu-
			     ment, arg,	taken as an integer of type (see

	      Get file status flags and	access modes; see
			     fcntl(5).

	      Set file status flags to
			     the  third	 argument, arg,	taken as an integer of
			     type Only certain flags can be set; see fcntl(5).
			     It	is not possible	to set both and

	      Get the first lock that blocks the lock
			     described	by  the	variable of type pointed to by
			     the third argument, arg, taken as	a  pointer  to
			     type The information retrieved overwrites the in-
			     formation passed to in the	structure.  If no lock
			     is	 found that would prevent this lock from being
			     created, the structure is passed back  unchanged,
			     except that the lock type is set to

	      Set  or  clear  a	file segment lock according to the variable of
	      type
			     pointed to	by the third argument, arg, taken as a
			     pointer  to type (see fcntl(5)).  The cmd is used
			     to	establish read and write locks,	as well	as  to
			     remove  either  type  of  lock If a read or write
			     lock cannot be set, returns immediately  with  an
			     error value of

	      This	     cmd is the	same as	except that if a read or write
			     lock is blocked by	other locks, the process  will
			     sleep until the segment is	free to	be locked.

	      If	     fildes refers to a	socket,	returns	the process or
			     process group ID  specified  to  receive  signals
			     when  out-of-band	data  is  available.  Positive
			     values indicate a process	ID;  negative  values,
			     other than	-1, indicate a process group ID.

	      If	     fildes  refers  to	 a socket, sets	the process or
			     process group ID  specified  to  receive  signals
			     when  out-of-band	data  is  available, using the
			     value of the third	argument, arg, taken  as  type
			     int.  Positive values indicate a process ID; neg-
			     ative values, other than -1, indicate  a  process
			     group ID.

	      Same as	     except arg	is a pointer to	instead	of

	      Same as	     except arg	is a pointer to	instead	of

	      Same as	     except arg	is a pointer to	instead	of

	      A	 read  lock  prevents any other	process	from write-locking the
	      protected	area.  More than one read lock can exist for  a	 given
	      segment of a file	at a given time.  The file descriptor on which
	      a	read lock is being placed must have been opened	with read  ac-
	      cess.

	      A	 write	lock  prevents	any other process from read-locking or
	      write-locking the	protected area.	 Only one write	lock may exist
	      for  a  given  segment  of a file	at a given time.  The file de-
	      scriptor on which	a write	lock is	being placed  must  have  been
	      opened with write	access.

	      The structure describes the type starting	offset relative	offset
	      size and process ID of the segment of the	file to	 be  affected.
	      The  process  ID	field  is only used with the cmd to return the
	      value of a block in lock.	 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  always  extend  to
	      the end of file by setting to zero (0).  If such a lock also has
	      set to zero (0), the whole file will be locked.  Changing	or un-
	      locking  a  segment  from	 the middle of a larger	locked segment
	      leaves two smaller segments for either end.  Locking  a  segment
	      already  locked  by the calling process causes the old lock type
	      to be removed and	the new	lock type to take effect.   All	 locks
	      associated  with	a  file	for a given process are	removed	when a
	      file descriptor for that file is closed by that process  or  the
	      process  holding that file descriptor terminates.	 Locks are not
	      inherited	by a child process in a	fork(2)	system call.

	      When enforcement-mode file and record locking is activated on  a
	      file (see	chmod(2)), future and system calls on the file are af-
	      fected by	the record locks in effect.

   Application Usage
       Because in the future the external  variable  will  be  set  to	EAGAIN
       rather  than  EACCES  when a section of a file is already locked	by an-
       other process, portable application programs should expect and test for
       either value.  For example:

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

	      Record locking, as implemented for NFS files, is only advisory.

RETURN VALUE
       Upon  successful	 completion, the value returned	depends	on cmd as fol-
       lows:

	      A	new file descriptor.

	      Value of close-on-exec flag (only	the low-order bit is defined).

	      Value other than -1.

	      Value of file status flags and access modes.

	      Value other than -1.

	      Value other than -1.

	      Value other than -1.

	      Value other than -1.

	      Value of process or process group	ID specified to	receive
			     signals when out-of-band data is available.

	      Value other than -1.

	      Value other than -1.

	      Value other than -1.

	      Value other than -1.

       Otherwise, a value of -1	is returned and	is set to indicate the error.

ERRORS
       fails if	any of the following conditions	occur:

	      [EBADF]	     fildes is not a valid open	 file  descriptor,  or
			     was  not  opened  for reading when	setting	a read
			     lock or for writing when setting a	write lock.

	      [EMFILE]	     cmd is and	the maximum number of file descriptors
			     is	currently open.

	      [EMFILE]	     cmd  is  or  the  type of lock is a read or write
			     lock, and no more file-locking headers are	avail-
			     able (too many files have segments	locked).

	      [EINVAL]	     cmd  is  and  arg is greater than or equal	to the
			     maximum number of file descriptors.

	      [EINVAL]	     cmd is and	arg is negative.

	      [EINVAL]	     cmd is or and arg or the data it points to	is not
			     valid,  or	 fildes	refers to a file that does not
			     support locking.

	      [EINVAL]	     cmd is not	a valid	command.

	      [EINVAL]	     cmd is and	both and are specified.

	      [EINTR]	     cmd is and	the call was interrupted by a signal.

	      [EACCES]	     cmd is the	type of	lock is	a read lock  or	 write
			     lock  and	the  segment of	a file to be locked is
			     already write-locked by another process,  or  the
			     type is a write lock and the segment of a file to
			     be	locked is already read-	or write-locked	by an-
			     other process.

	      [ENOLCK]	     cmd  is  or  the  type of lock is a read or write
			     lock, and no more file-locking headers are	avail-
			     able (too many files have segments	locked), or no
			     more record locks are available  (too  many  file
			     segments locked).

	      [ENOLCK]	     cmd  is  or  the  type  of	lock is	a read lock or
			     write lock	and the	file is	an NFS file  with  ac-
			     cess bits set for enforcement mode.

	      [ENOLCK]	     cmd  is  or the file is an	NFS file, and a	system
			     error occurred on the remote node.

	      [EOVERFLOW]    cmd is and	the blocking lock's starting offset or
			     length would not fit in the caller's structure.

	      [EDEADLK]	     cmd  is  when  the	lock is	blocked	by a lock from
			     another process and sleeping (waiting)  for  that
			     lock to become free.  This	causes a deadlock sit-
			     uation.

	      [EAGAIN]	     cmd is or and the file is mapped  in  to  virtual
			     memory via	the system call	(see mmap(2)).

	      [EFAULT]	     cmd is either or and arg points to	an illegal ad-
			     dress.

	      [ENOTSOCK]     cmd is or and fildes does not refer to a socket.

AUTHOR
       was developed by	HP, AT&T and the University of California, Berkeley.

SEE ALSO
       lockd(1M),  statd(1M),	chmod(2),   close(2),	creat64(2),   exec(2),
       lockf(2), open(2), read(2), write(2), fcntl(5).

STANDARDS CONFORMANCE
								      fcntl(2)

NAME | SYNOPSIS | DESCRIPTION | NETWORKING FEATURES | RETURN VALUE | ERRORS | AUTHOR | SEE ALSO | STANDARDS CONFORMANCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=fcntl&sektion=2&manpath=HP-UX+11.22>

home | help