File: *manpages*,  Node: fcntl,  Up: (dir)



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

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

       F_DUPFD  Makes arg be a copy of fd, closing  fd  first  if
                necessary.

                The   same   functionality  can  be  more  easily
                achieved by using dup2(2).

                The old and new descriptors may  be  used  inter
                changeably.   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 be closed
                on exec.

                On success, the new descriptor is returned.

       F_GETFD  Read the close-on-exec flag.   If  the  low-order
                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  arg (only the least significant bit is used).

       F_GETFL  Read the descriptor's flags (all flags (as set by
                open(2)) are returned).

       F_SETFL  Set the descriptor's flags to the value specified
                by arg.  Only O_APPEND and O_NONBLOCK may be set.

                The  flags  are  shared between copies (made with
                dup etc.) of the same file descriptor.

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

Linux                   26 September 1995                       1

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

       F_GETLK, F_SETLK and F_SETLKW
                Manage discretionary file locks.  The third argu
                ment arg is a pointer to a struct flock (that may
                be overwritten by this call).

       F_GETLK  Return  the flock structure that prevents us from
                obtaining the lock, or set the  l_type  field  of
                the lock to F_UNLCK if there is no obstruction.

       F_SETLK  The  lock  is  set  (when  l_type  is  F_RDLCK or
                F_WRLCK) or cleared (when it is F_UNLCK).  If the
                lock  is  held by someone else, this call returns
                -1 and sets errno to EACCES or EAGAIN.

       F_SETLKW Like F_SETLK, but instead of returning  an  error
                we wait for the lock to be released.  If a signal
                that is to be caught is received while fcntl() is
                waiting,  it  is  interrupted and returns immedi
                ately (with return value  -1  and  errno  set  to
                EINTR).

       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.

                If  you  set  the  O_ASYNC  status flag on a file
                descriptor (either by providing  this  flag  with
                the open 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  sig
                nal 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 SIG
                URG signals that are delivered  when  out-of-band
                data  arrives  on that socket. (SIGURG is sent in
                any  situation  where  select  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 fore
                ground process group of the terminal.

                The use of O_ASYNC, F_GETOWN,  F_SETOWN  is  BSD-
                specific.   POSIX  has  asynchronous  I/O and the
                aio_sigevent structure to achieve similar things.

Linux                   26 September 1995                       2

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

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_SETFD, F_SETFL, F_GETLK, F_SETLK,  F_SETLKW  Some  value
                different from -1.

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

ERRORS
       EACCES   Operation is prohibited by locks  held  by  other
                processes.

       EAGAIN   Operation is prohibited because the file has been
                memory-mapped by another process.

       EDEADLK  It was detected that the specified F_SETLKW  com
                mand would cause a deadlock.

       EBADF    fd is not an open file descriptor.

       EINTR    The F_SETLKW command was interrupted by a signal.

       EINVAL   For F_DUPFD, arg is negative or is  greater  than
                the maximum allowable value.

       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.

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

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. 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  sup
       ports several other options and flags not documented here.

       POSIX.1 documents an  additional  EINTR  condition.   SVr4

Linux                   26 September 1995                       3

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

       documents  additional  EFAULT,  EINTR,  EIO,  ENOLINK  and
       EOVERFLOW error conditions.

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

Linux                   26 September 1995                       4

