Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for fcntl (redhat section 2)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

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 operation 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 descriptors, the position is also changed for the other.

	      The two descriptors do not share the close-on-exec flag,	however.   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  modi-
       fied  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 creation flags) in arg are ignored.  On
	      Linux this command can only change the O_APPEND, O_NONBLOCK, O_ASYNC, and  O_DIRECT

   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 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 precisely 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 inter-
	      rupted and (after the signal 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 hold-
	      ing 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  automatically  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

       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 mandatory, 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.  Manda-
       tory locks are enforced for all processes.

   Managing signals
       F_GETOWN, F_SETOWN, F_GETSIG and F_SETSIG are used to manage I/O availability 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 sig-
	      nal 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 recipient 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  condition".)   If	the  file
	      descriptor  corresponds  to  a  terminal device, 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 han-
	      dler if installed with SA_SIGINFO.

	      By using F_SETSIG with a non-zero value, and setting SA_SIGINFO for the signal han-
	      dler  (see  sigaction(2)), extra information about I/O events is passed to the han-
	      dler in a siginfo_t structure.  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  han-
	      dler, 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_SET-
       SIG  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

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

		     Take  out	a  write  lease.   This will cause us to be notified 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.

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

       When the contestant performs an open() or truncate() that conflicts with  a  lease  estab-
       lished  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  EWOULD-
       BLOCK).	 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

       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 handler 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
	      (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 speci-
	      fied  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 application must re-regis-
	      ter to receive further notifications.  Alternatively, if DN_MULTISHOT  is  included
	      in arg, then notification 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  signal  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  han-
	      dler  was  established using SA_SIGINFO) and the si_fd field of this structure con-
	      tains the file descriptor which generated the notification (useful when  establish-
	      ing notification on multiple directories).

	      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 prohib-
	      ited 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 before the lock was  checked  or	acquired.
	      Most  likely  when locking 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

       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

       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 differ-
       ent machine.

       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.

       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)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 02:53 PM.