Seth Woolley's Man Viewer

fcntl(2) - fcntl, fcntl - manipulate file descriptor - man 2 fcntl

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

FCNTL(2)                   Linux Programmer's Manual                  FCNTL(2)



NAME
       fcntl - manipulate file(1,n) 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(1,2) *lock);

DESCRIPTION
       fcntl  performs  one  of  various  miscellaneous operations on fd.  The
       operation in(1,8) question is determined by cmd.

   Handling close-on-exec
       F_DUPFD
              Find the lowest numbered available file(1,n) 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(1,n) position pointers and flags; for example, if(3,n)
              the file(1,n) 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(1,n) will remain open(2,3,n) across exec(3,n,1 builtins), 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(1,n) status flags
       A file(1,n) descriptor has certain associated flags, initialized by  open(2,3,n)(2)
       and possibly modified by fcntl(2).  The flags are shared between copies
       (made with dup(2), fork(2), etc.) of the same file(1,n) descriptor.

       The flags and their semantics are described in(1,8) open(2,3,n)(2).

       F_GETFL
              Read the file(1,n) descriptor's flags.

       F_SETFL
              Set the file(1,n) status flags part of the descriptor's flags to  the
              value  specified by arg.  Remaining bits (access(2,5) mode, file(1,n) cre-
              ation flags) in(1,8) 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(1,8) unspecified order).

         struct flock(1,2) {
             ...
             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(1,n)  (if(3,n)
       l_whence  is  SEEK_SET);  the  current  file(1,n)  offset  (if(3,n)  l_whence  is
       SEEK_CUR); or the end of the file(1,n) (if(3,n) 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(1,n) 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(1,n), no matter how large the file(1,n)
       grows.

       The l_type field can be used to place  a  read(2,n,1 builtins)  (F_RDLCK)  or  a  write(1,2)
       (F_WDLCK) lock on a file.  Any number of processes may hold a read(2,n,1 builtins) lock
       (shared lock) on a file(1,n) region, but only one process may hold  a  write(1,2)
       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(1,n) region; if(3,n) 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(3,n) 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(3,n) a conflicting lock is held on the file(1,n),
              then wait for that lock to be released.  If a signal(2,7)  is  caught
              while  waiting, then the call is interrupted and (after the sig-
              nal(2,7) handler has returned) returns immediately (with return value
              -1 and errno set(7,n,1 builtins) 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(1,8) 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(1,8)
              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(2,n,1 builtins) lock, fd must be open(2,3,n) for reading.   In  order
       to  place  a  write(1,2)  lock,  fd must be open(2,3,n) for writing.  To place both
       types of lock, open(2,3,n) a file(1,n) read-write.

       As well as being removed by an explicit F_UNLCK, record locks are auto-
       matically released when the process terminates or if(3,n) it closes any file(1,n)
       descriptor referring to a file(1,n) on which locks are held.  This  is  bad:
       it  means  that a process can lose the locks on a file(1,n) like /etc/passwd(1,5)
       or /etc/mtab when for some reason a library function decides  to  open(2,3,n),
       read(2,n,1 builtins) and close(2,7,n) 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(1,8) that package should be avoided; use
       read(2,n,1 builtins)(2) and write(1,2)(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(2,8)(8))  for  the  file(1,n)  system  containing the file(1,n) to be locked and
       enabled on the file(1,n) itself (by disabling group  execute  permission  on
       the file(1,n) 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(1,n)  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(1,n) descriptor fd.  Process groups
              are  specified  using negative values.  (F_SETSIG can be used to
              specify a different signal(2,7) instead of SIGIO).

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

              The  process  or  process  group  to  receive  the signal(2,7) can be
              selected by using the F_SETOWN command to  the  fcntl  function.
              If the file(1,n) descriptor is a socket(2,7,n), 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(1,8) any situation where
              select(2,7,2 select_tut)(2) would report the socket(2,7,n) as having an "exceptional con-
              dition".)   If  the  file(1,n)  descriptor  corresponds to a terminal
              device, then SIGIO signals are sent to  the  foreground  process
              group of the terminal.

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

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

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

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

       Using  these mechanisms, a program can implement fully asynchronous I/O
       without using select(2,7,2 select_tut)(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(1,8) 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(1,n) referred to by fd.  A file(1,n) lease provides a mechanism
       whereby the process holding the lease (the "lease holder") is  notified
       (via  delivery  of a signal(2,7)) when another process (the "lease breaker")
       tries to open(2,3,n)(2) or truncate(2,7)(2) that file.

       F_SETLEASE
              Set or remove a file(1,n) lease according to which of  the  following
              values is specified in(1,8) the integer arg:


              F_RDLCK
                     Take out a read(2,n,1 builtins) lease.  This will cause us to be notified
                     when another process opens the file(1,n) for writing or  trun-
                     cates it.

              F_WRLCK
                     Take  out  a write(1,2) lease.  This will cause us to be noti-
                     fied when another process opens the file(1,n) (for reading  or
                     writing) or truncates it.  A write(1,2) lease may be placed on
                     a file(1,n) only if(3,n) no other process currently  has  the  file(1,n)
                     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(1,n) whose UID matches the  file(1,n)  system
       UID  of  the process.  A process with the CAP_LEASE capability may take
       out leases on arbitrary files.

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

       When a process (the "lease breaker") performs an open(2,3,n)()  or  truncate(2,7)()
       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(2,3,n)(),  in(1,8)  which  case  the  system  call  will return with the error(8,n)
       EWOULDBLOCK.  The kernel notifies the lease holder by sending it a sig-
       nal(2,7)  (SIGIO by default).  The lease holder should respond to receipt of
       this signal(2,7) by doing whatever cleanup is required  in(1,8)  preparation  for
       the  file(1,n)  to  be  accessed  by  another process (e.g., flushing cached
       buffers) and then either remove or downgrade its  lease.   A  lease  is
       removed  by performing an F_SETLEASE command specifying arg as F_UNLCK.
       If we currently hold a write(1,2) lease on the file(1,n), and the  lease  breaker
       is opening the file(1,n) for reading, then it is sufficient to downgrade the
       lease to a read(2,n,1 builtins) lease.  This is done by performing an  F_SETLEASE  com-
       mand specifying arg as F_RDLCK.

       If  the  lease holder fails to downgrade or remove the lease within the
       number of seconds specified in(1,8) /proc(5,n)/sys/fs/lease-break-time  then  the
       kernel forcibly removes or downgrades the lease holder's lease.

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

       The  default  signal(2,7) 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(2,7) 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(1,n)  that  has  been
       accessed  by  another  process.   (This  is  useful if(3,n) 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(1,8) arg,  which
              is  a  bit  mask specified by ORing together zero or more of the
              following bits:


              Bit         Description (event in(1,8) directory)
              -------------------------------------------------------------
              DN_ACCESS   A file(1,n) was accessed (read(2,n,1 builtins), pread, readv)
              DN_MODIFY   A file(1,n) was modified (write(1,2), pwrite,
                          writev, truncate(2,7), ftruncate)
              DN_CREATE   A file(1,n) was created (open(2,3,n), creat, mknod(1,2),
                          mkdir(1,2), link(1,2), symlink, rename(1,2,n))
              DN_DELETE   A file(1,n) was unlinked (unlink(1,2), rename(1,2,n) to
                          another directory, rmdir(1,2))
              DN_RENAME   A file(1,n) was renamed within this
                          directory (rename(1,2,n))
              DN_ATTRIB   The attributes of a file(1,n) were changed
                          (chown(1,2), chmod(1,2), 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(3,n) DN_MULTISHOT is included in(1,8) arg, then notifi-
              cation will remain in(1,8) effect until explicitly removed.

              A series of F_NOTIFY requests is cumulative, with the events  in(1,8)
              arg  being added to the set(7,n,1 builtins) already monitored.  To disable noti-
              fication of all events, make an F_NOTIFY call specifying arg  as
              0.

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

              Especially when using DN_MULTISHOT, a POSIX.1b real time(1,2,n)  signal(2,7)
              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(2,7) sent when read(2,n,1 builtins) or write(1,2) becomes  possible,  or
                zero for traditional SIGIO behaviour.

       All other commands
                Zero.

       On error(8,n), -1 is returned, and errno is set(7,n,1 builtins) appropriately.

ERRORS
       EACCES or EAGAIN
              Operation  is  prohibited by locks held by other processes.  Or,
              operation is prohibited because the file(1,n) has been  memory-mapped
              by another process.

       EBADF  fd is not an open(2,3,n) file(1,n) descriptor, or the command was F_SETLK or
              F_SETLKW and the file(1,n) descriptor open(2,3,n) 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(2,7)
              before the lock was checked or acquired.  Most likely when lock-
              ing  a  remote  file(1,n)  (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(2,7)
              number.

       EMFILE For F_DUPFD, the process already has the maximum number of  file(1,n)
              descriptors open.

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

       EPERM  Attempted to clear(1,3x,3x clrtobot) the O_APPEND flag on  a  file(1,n)  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(1,2)(2) and fcntl(2).

       POSIX  1003.1-2001  allows  l_len  to  be  negative. (And if(3,n) it is, the
       interval described by the lock covers bytes  l_start+l_len  up  to  and
       including  l_start-1.)   This  is supported by Linux since Linux 2.4.21
       and 2.5.49.

       Several systems have more fields in(1,8) struct flock(1,2) such as e.g.  l_sysid.
       Clearly,  l_pid  alone  is  not  going to be very useful if(3,n) 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(1,8) POSIX.1.  F_GETOWN and F_SETOWN are BSDisms not  supported
       in(1,8)  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,3,n)(2) and vary
       between  these  systems; O_APPEND, O_NONBLOCK, O_RDONLY, and O_RDWR are
       specified in(1,8) POSIX.1.  SVr4 supports several other  options  and  flags
       not documented here.

       SVr4  documents additional EIO, ENOLINK and EOVERFLOW error(8,n) conditions.

SEE ALSO
       dup2(2), flock(1,2)(2), open(2,3,n)(2), socket(2,7,n)(2), lockf(3), capabilities(7)

       See    also    locks.txt,    mandatory.txt,    and    dnotify.txt    in(1,8)
       /usr/src/linux/Documentation.



Linux 2.6.6                       2004-05-27                          FCNTL(2)

References for this manual (incoming links)