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

FreeBSD Manual Pages


home | help
FCNTL(2)		   Linux Programmer's Manual		      FCNTL(2)

       fcntl - manipulate file descriptor

       #include	<unistd.h>
       #include	<fcntl.h>

       int fcntl(int fd, int cmd);
       int fcntl(int fd, int cmd, long arg);
       int fcntl(int fd, int cmd, struct flock *lock);

       fcntl  performs one of various miscellaneous operations on fd.  The op-
       eration in question is determined by cmd.

   Handling close-on-exec
	      Find the lowest numbered available file descriptor greater  than
	      or  equal	to arg and make	it be a	copy of	fd.  This is different
	      form dup2(2) which uses exactly the descriptor specified.

	      The old and new descriptors may be  used	interchangeably.  They
	      share  locks,  file position pointers and	flags; for example, if
	      the file position	is modified by using lseek on one of  the  de-
	      scriptors, the position is also changed for the other.

	      The  two	descriptors  do	not share the close-on-exec flag, how-
	      ever.  The close-on-exec flag of the copy	is off,	 meaning  that
	      it will not be closed on exec.

	      On success, the new descriptor is	returned.

	      Read  the	 close-on-exec	flag.  If the FD_CLOEXEC bit is	0, the
	      file will	remain open across exec, otherwise it will be closed.

	      Set the  close-on-exec  flag  to	the  value  specified  by  the
	      FD_CLOEXEC bit of	arg.

   The file status flags
       A  file descriptor has certain associated flags,	initialized by open(2)
       and possibly modified by	fcntl(2).  The flags are shared	between	copies
       (made with dup(2), fork(2), etc.) of the	same file descriptor.

       The flags and their semantics are described in open(2).

	      Read the file descriptor's flags.

	      Set  the file status flags part of the descriptor's flags	to the
	      value specified by arg.  Remaining bits (access mode, file  cre-
	      ation flags) in arg are ignored.	On Linux this command can only
	      change the O_APPEND, O_NONBLOCK, O_ASYNC,	and O_DIRECT flags.

   Advisory locking
       F_GETLK,	F_SETLK	and F_SETLKW are used to acquire,  release,  and  test
       for  the	existence of record locks (also	known as file-segment or file-
       region locks).  The third argument lock is a  pointer  to  a  structure
       that has	at least the following fields (in unspecified order).

	 struct	flock {
	     short l_type;    /* Type of lock: F_RDLCK,
				 F_WRLCK, F_UNLCK */
	     short l_whence;  /* How to	interpret l_start:
	     off_t l_start;   /* Starting offset for lock */
	     off_t l_len;     /* Number	of bytes to lock */
	     pid_t l_pid;     /* PID of	process	blocking our lock
				 (F_GETLK only)	*/

       The  l_whence,  l_start,	and l_len fields of this structure specify the
       range of	bytes we wish to lock.	l_start	is the starting	offset for the
       lock,  and is interpreted relative to either: the start of the file (if
       l_whence	 is  SEEK_SET);	 the  current  file  offset  (if  l_whence  is
       SEEK_CUR);  or  the  end	of the file (if	l_whence is SEEK_END).	In the
       final two cases,	l_start	can be a negative number provided  the	offset
       does not	lie before the start of	the file.  l_len is a non-negative in-
       teger (but see the NOTES	below) specifying the number of	 bytes	to  be
       locked.	 Bytes	past  the end of the file may be locked, but not bytes
       before the start	of the file.  Specifying 0 for l_len has  the  special
       meaning:	 lock all bytes	starting at the	location specified by l_whence
       and l_start through to the end of file, no matter how  large  the  file

       The  l_type  field  can	be  used  to place a read (F_RDLCK) or a write
       (F_WDLCK) lock on a file.  Any number of	processes may hold a read lock
       (shared	lock)  on a file region, but only one process may hold a write
       lock (exclusive lock). An exclusive lock	excludes all other locks, both
       shared  and exclusive.  A single	process	can hold only one type of lock
       on a file region; if a new lock is applied to an	already-locked region,
       then  the  existing  lock is converted to the the new lock type.	 (Such
       conversions may involve splitting, shrinking, or	coalescing with	an ex-
       isting  lock  if	the byte range specified by the	new lock does not pre-
       cisely coincide with the	range of the existing lock.)

	      Acquire a	lock (when l_type is F_RDLCK or	F_WRLCK) or release  a
	      lock  (when  l_type  is  F_UNLCK)	 on the	bytes specified	by the
	      l_whence,	l_start, and l_len fields of lock.  If	a  conflicting
	      lock  is	held by	another	process, this call returns -1 and sets
	      errno to EACCES or EAGAIN.

	      As for F_SETLK, but if a conflicting lock	is held	on  the	 file,
	      then  wait  for that lock	to be released.	 If a signal is	caught
	      while waiting, then the call is interrupted and (after the  sig-
	      nal handler has returned)	returns	immediately (with return value
	      -1 and errno set to EINTR).

	      On input to this call, lock describes a lock we  would  like  to
	      place  on	 the  file.  If	the lock could be placed, fcntl() does
	      not actually place it, but returns F_UNLCK in the	 l_type	 field
	      of  lock and leaves the other fields of the structure unchanged.
	      If one or	more incompatible locks	would prevent this lock	 being
	      placed, then fcntl() returns details about one of	these locks in
	      the l_type, l_whence, l_start, and l_len fields of lock and sets
	      l_pid to be the PID of the process holding that lock.

       In  order  to place a read lock,	fd must	be open	for reading.  In order
       to place	a write	lock, fd must be open  for  writing.   To  place  both
       types of	lock, open a file read-write.

       As well as being	removed	by an explicit F_UNLCK,	record locks are auto-
       matically released when the process terminates or if it closes any file
       descriptor  referring  to a file	on which locks are held.  This is bad:
       it means	that a process can lose	the locks on a file  like  /etc/passwd
       or  /etc/mtab  when for some reason a library function decides to open,
       read and	close it.

       Record locks are	not inherited by a child created via fork(2), but  are
       preserved across	an execve(2).

       Because	of the buffering performed by the stdio(3) library, the	use of
       record locking with routines in that package  should  be	 avoided;  use
       read(2) and write(2) instead.

   Mandatory locking
       (Non-POSIX.)   The  above record	locks may be either advisory or	manda-
       tory, and are advisory by default.  To make  use	 of  mandatory	locks,
       mandatory  locking  must	 be  enabled  (using  the  "-o mand" option to
       mount(8)) for the file system containing	the file to be locked and  en-
       abled  on the file itself (by disabling group execute permission	on the
       file and	enabling the set-GID permission	bit).

       Advisory	locks are not enforced and are useful only between cooperating
       processes. Mandatory locks are enforced for all processes.

   Managing signals
       F_GETOWN, F_SETOWN, F_GETSIG and	F_SETSIG are used to manage I/O	avail-
       ability signals:

	      Get the process ID or process group  currently  receiving	 SIGIO
	      and  SIGURG  signals  for	events on file descriptor fd.  Process
	      groups are returned as negative values.

	      Set the process ID or process group that will receive SIGIO  and
	      SIGURG signals for events	on file	descriptor fd.	Process	groups
	      are specified using negative values.  (F_SETSIG can be  used  to
	      specify a	different signal instead of SIGIO).

	      If  you set the O_ASYNC status flag on a file descriptor (either
	      by providing this	flag with the open(2) call, or	by  using  the
	      F_SETFL command of fcntl), a SIGIO signal	is sent	whenever input
	      or output	becomes	possible on that file descriptor.

	      The process or process group to receive the signal  can  be  se-
	      lected  by using the F_SETOWN command to the fcntl function.  If
	      the file descriptor is a socket, this also selects the recipient
	      of  SIGURG  signals that are delivered when out-of-band data ar-
	      rives on that socket.  (SIGURG is	sent in	 any  situation	 where
	      select(2)	would report the socket	as having an "exceptional con-
	      dition".)	 If the	file descriptor	corresponds to a terminal  de-
	      vice,  then  SIGIO  signals  are	sent to	the foreground process
	      group of the terminal.

	      Get the signal sent when input or	output	becomes	 possible.   A
	      value  of	 zero means SIGIO is sent.  Any	other value (including
	      SIGIO) is	the signal sent	instead, and in	this  case  additional
	      info  is	available  to  the  signal  handler  if	installed with

	      Sets the signal sent when	input or output	becomes	 possible.   A
	      value of zero means to send the default SIGIO signal.  Any other
	      value (including SIGIO) is the signal to send  instead,  and  in
	      this  case additional info is available to the signal handler if
	      installed	with SA_SIGINFO.

	      By using F_SETSIG	with a non-zero	value, and setting  SA_SIGINFO
	      for  the	signal	handler	 (see sigaction(2)), extra information
	      about I/O	events is passed to the	handler	in a siginfo_t	struc-
	      ture.   If  the  si_code field indicates the source is SI_SIGIO,
	      the si_fd	field gives the	file descriptor	 associated  with  the
	      event.  Otherwise, there is no indication	which file descriptors
	      are pending, and you should use the usual	mechanisms (select(2),
	      poll(2),	read(2)	 with  O_NONBLOCK set etc.) to determine which
	      file descriptors are available for I/O.

	      By selecting a POSIX.1b real time	signal	(value	>=  SIGRTMIN),
	      multiple I/O events may be queued	using the same signal numbers.
	      (Queuing is dependent on available memory).   Extra  information
	      is  available  if	 SA_SIGINFO  is	set for	the signal handler, as

       Using these mechanisms, a program can implement fully asynchronous  I/O
       without using select(2) or poll(2) most of the time.

       The  use	 of  O_ASYNC, F_GETOWN,	F_SETOWN is specific to	BSD and	Linux.
       F_GETSIG	and F_SETSIG are Linux-specific.  POSIX	has  asynchronous  I/O
       and  the	 aio_sigevent  structure  to achieve similar things; these are
       also available in Linux as part of the GNU C Library (Glibc).

       F_SETLEASE and F_GETLEASE (Linux	2.4 onwards) are  used	(respectively)
       to  establish and retrieve the current setting of the calling process's
       lease on	the file referred to by	fd.  A file lease provides a mechanism
       whereby	the process holding the	lease (the "lease holder") is notified
       (via delivery of	a signal)  when	 another  process  (the	 "contestant")
       tries to	open(2)	or truncate(2) that file.

	      Set  or  remove a	file lease according to	which of the following
	      values is	specified in the integer arg:

		     Take out a	read lease.  This will cause us	to be notified
		     when  another process opens the file for writing or trun-
		     cates it.

		     Take out a	write lease.  This will	cause us to  be	 noti-
		     fied  when	another	process	opens the file (for reading or
		     writing) or truncates it.	A write	lease may be placed on
		     a	file  only  if no other	process	currently has the file

		     Remove our	lease from the file.

       A process may hold only one type	of lease on a file.

       Leases may only be taken	out on regular files.  An unprivileged process
       may  only  take out a lease on a	file whose UID matches the file	system
       UID of the process.

	      Indicates	what type of lease we hold on the file referred	to  by
	      fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating,
	      respectively, that the calling process holds a read, a write, or
	      no  lease	 on the	file.  (The third argument to fcntl() is omit-

       When the	contestant performs an open()  or  truncate()  that  conflicts
       with  a lease established via F_SETLEASE, the system call is blocked by
       the kernel (unless the O_NONBLOCK flag  was  specified  to  open(),  in
       which  case  it	returns	 immediately with the error EWOULDBLOCK).  The
       kernel then notifies the	lease holder by	sending	it a signal (SIGIO  by
       default).  The lease holder should respond to receipt of	this signal by
       doing whatever cleanup is required in preparation for the  file	to  be
       accessed	 by  another  process (e.g., flushing cached buffers) and then
       remove its lease	by performing an F_SETLEASE command specifying arg  as

       If  the	lease  holder  fails to	release	the lease within the number of
       seconds specified in /proc/sys/fs/lease-break-time and the contestant's
       system  call  remains  blocked  (i.e.,  the  contestant did not specify
       O_NONBLOCK on its open()	call, and the system call was not  interrupted
       by  a  signal  handler)	then  the  kerrnel  forcibly  breaks the lease
       holder's	lease.

       Once the	lease has been voluntarily or forcibly removed,	 and  assuming
       the  contestant	has  not unblocked its system call, the	kernel permits
       the contestant's	system call to proceed.

       The default signal used to notify the lease holder is SIGIO,  but  this
       can  be	changed	using the F_SETSIG command to fcntl ().	 If a F_SETSIG
       command is performed (even one specifying SIGIO), and the  signal  han-
       dler  is	 established using SA_SIGINFO, then the	handler	will receive a
       siginfo_t sructure as its second	argument, and the si_fd	field of  this
       argument	 will hold the descriptor of the leased	file that has been ac-
       cessed by another process.  (This is useful if the caller holds	leases
       against multiple	files).

   File	and directory change notification
	      (Linux  2.4 onwards) Provide notification	when the directory re-
	      ferred to	by fd or any of	the files that it contains is changed.
	      The  events  to be notified are specified	in arg,	which is a bit
	      mask specified by	ORing together zero or more of	the  following

	      Bit	  Description (event in	directory)
	      DN_ACCESS	  A file was accessed (read, pread, readv)
	      DN_MODIFY	  A file was modified (write, pwrite,
			  writev, truncate, ftruncate)
	      DN_CREATE	  A file was created (open, creat, mknod,
			  mkdir, link, symlink,	rename)
	      DN_DELETE	  A file was unlinked (unlink, rename to
			  another directory, rmdir)
	      DN_RENAME	  A file was renamed within this
			  directory (rename)
	      DN_ATTRIB	  The attributes of a file were	changed
			  (chown, chmod, utime[s])

	      (In  order  to  obtain  these definitions, the _GNU_SOURCE macro
	      must be defined before including <fcntl.h>.)

	      Directory	notifications are normally "one-shot", and the	appli-
	      cation  must  re-register	to receive further notifications.  Al-
	      ternatively, if DN_MULTISHOT is included in arg, then  notifica-
	      tion  will  remain in effect until explicitly removed.  A	series
	      of calls specifying DN_MULTISHOT is cumulative, with the	events
	      in arg being added to the	set already monitored.	To disable no-
	      tification of all	events,	make an	F_NOTIFY call  specifying  arg
	      as 0.

	      Notification  occurs via delivery	of a signal.  The default sig-
	      nal is SIGIO, but	this can be changed using the F_SETSIG command
	      to  fcntl().   In	the latter case, the signal handler receives a
	      siginfo_t	structure as its second	argument (if the  handler  was
	      established using	SA_SIGINFO) and	the si_fd field	of this	struc-
	      ture contains the	file descriptor	which generated	the  notifica-
	      tion (useful when	establishing notification on multiple directo-

	      Especially when using DN_MULTISHOT, a POSIX.1b real time	signal
	      should  be  used	for notication,	so that	multiple notifications
	      can be queued.

       For a successful	call, the return value depends on the operation:

       F_DUPFD	The new	descriptor.

       F_GETFD	Value of flag.

       F_GETFL	Value of flags.

       F_GETOWN	Value of descriptor owner.

       F_GETSIG	Value of signal	sent when read or write	becomes	 possible,  or
		zero for traditional SIGIO behaviour.

       All other commands

       On error, -1 is returned, and errno is set appropriately.

	      Operation	 is  prohibited	by locks held by other processes.  Or,
	      operation	is prohibited because the file has been	 memory-mapped
	      by another process.

       EBADF  fd is not	an open	file descriptor, or the	command	was F_SETLK or
	      F_SETLKW and the file descriptor open mode  doesn't  match  with
	      the type of lock requested.

	      It  was detected that the	specified F_SETLKW command would cause
	      a	deadlock.

       EFAULT lock is outside your accessible address space.

       EINTR  For F_SETLKW, the	command	was  interrupted  by  a	 signal.   For
	      F_GETLK and F_SETLK, the command was interrupted by a signal be-
	      fore the lock was	checked	or acquired.  Most likely when locking
	      a	 remote	file (e.g. locking over	NFS), but can sometimes	happen

       EINVAL For F_DUPFD, arg is negative or is greater than the maximum  al-
	      lowable  value.	For  F_SETSIG,	arg is not an allowable	signal

       EMFILE For F_DUPFD, the process already has the maximum number of  file
	      descriptors open.

       ENOLCK Too  many	 segment  locks	 open, lock table is full, or a	remote
	      locking protocol failed (e.g. locking over NFS).

       EPERM  Attempted	to clear the O_APPEND flag on a	file that has the  ap-
	      pend-only	attribute set.

       The  errors  returned  by  dup2	are  different	from those returned by

       Since kernel 2.0, there is no interaction between  the  types  of  lock
       placed by flock(2) and fcntl(2).

       POSIX  1003.1-2001  allows l_len	to be negative.	(And if	it is, the in-
       terval described	by the lock covers bytes l_start+l_len up to  and  in-
       cluding l_start-1.)  However, for current kernels the Linux system call
       returns EINVAL in this situation.

       Several systems have more fields	in struct flock	such as	e.g.  l_sysid.
       Clearly,	 l_pid	alone  is  not	going to be very useful	if the process
       holding the lock	may live on a different	machine.

       SVr4, SVID, POSIX, X/OPEN,  BSD	4.3.   Only  the  operations  F_DUPFD,
       specified in POSIX.1.  F_GETOWN and F_SETOWN are	BSDisms	not  supported
       in  SVr4;  F_GETSIG  and	 F_SETSIG  are	specific  to Linux.  F_NOTIFY,
       F_GETLEASE, and F_SETLEASE are Linux specific.  (Define the _GNU_SOURCE
       macro  before  including	 <fcntl.h>  to obtain these definitions.)  The
       flags legal for F_GETFL/F_SETFL are those supported by open(2) and vary
       between	these  systems;	O_APPEND, O_NONBLOCK, O_RDONLY,	and O_RDWR are
       specified in POSIX.1.  SVr4 supports several other  options  and	 flags
       not documented here.

       SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions.

       dup2(2),	flock(2), lockf(3), open(2), socket(2)

       See    also    locks.txt,    mandatory.txt,    and    dnotify.txt    in

Linux-2.5.18			  2002-04-24			      FCNTL(2)


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

home | help