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

FreeBSD Manual Pages

  
 
  

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

NAME
       fcntl - manipulate file descriptor

SYNOPSIS
       #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);

DESCRIPTION
       fcntl  performs	one  of	 various  miscellaneous	operations on fd.  The
       operation in question is	determined by cmd.

   Handling close-on-exec
       F_DUPFD
	      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
	      descriptors, 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.

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

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

       F_GETFL
	      Read the file descriptor's flags.

       F_SETFL
	      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:
				 SEEK_SET, SEEK_CUR, SEEK_END */
	     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
       integer (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
       grows.

       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
       existing	lock if	the byte range specified by the	new lock does not pre-
       cisely coincide with the	range of the existing lock.)

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

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

       F_GETLK
	      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
       enabled	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:

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

       F_SETOWN
	      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
	      selected	by  using  the F_SETOWN	command	to the fcntl function.
	      If the file descriptor is	a socket, this also selects the	recip-
	      ient  of SIGURG signals that are delivered when out-of-band data
	      arrives 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
	      device,  then  SIGIO  signals are	sent to	the foreground process
	      group of the terminal.

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

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

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

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

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

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

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

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

       F_GETLEASE
	      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-
	      ted.)

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

       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
       accessed	by another process.  (This  is	useful	if  the	 caller	 holds
       leases against multiple files).

   File	and directory change notification
       F_NOTIFY
	      (Linux  2.4  onwards)  Provide  notification  when the directory
	      referred 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	bits:

	      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.
	      Alternatively, if	DN_MULTISHOT is	included in arg, then  notifi-
	      cation 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
	      notification 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-
	      ries).

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

RETURN VALUE
       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
		Zero.

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

ERRORS
       EACCES or EAGAIN
	      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.

       EDEADLK
	      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
	      before the lock was checked or acquired.	Most likely when lock-
	      ing  a  remote  file  (e.g. locking over NFS), but can sometimes
	      happen locally.

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

       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
	      append-only attribute set.

NOTES
       The  errors  returned  by  dup2	are  different	from those returned by
       F_DUPFD.

       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
       interval	described by the lock covers bytes  l_start+l_len  up  to  and
       including  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.

CONFORMING TO
       SVr4, SVID, POSIX, X/OPEN,  BSD	4.3.   Only  the  operations  F_DUPFD,
       F_GETFD,	 F_SETFD,  F_GETFL, F_SETFL, F_GETLK, F_SETLK and F_SETLKW are
       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.

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

       See    also    locks.txt,    mandatory.txt,    and    dnotify.txt    in
       /usr/src/linux/Documentation.

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

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | NOTES | CONFORMING TO | SEE ALSO

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

home | help