oracular (3) fcntl.3posix.gz

Provided by: manpages-posix-dev_2017a-2_all bug

PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of this interface
       may differ (consult the corresponding Linux manual page for details of Linux behavior), or the  interface
       may not be implemented on Linux.

NAME

       fcntl — file control

SYNOPSIS

       #include <fcntl.h>

       int fcntl(int fildes, int cmd, ...);

DESCRIPTION

       The fcntl() function shall perform the operations described below on open files. The fildes argument is a
       file descriptor.

       The available values for cmd are defined in <fcntl.h> and are as follows:

       F_DUPFD       Return a new file descriptor which shall be allocated as described in  Section  2.14,  File
                     Descriptor  Allocation,  except  that  it  shall  be  the  lowest  numbered  available file
                     descriptor greater than or equal to the third argument, arg, taken as an  integer  of  type
                     int.  The new file descriptor shall refer to the same open file description as the original
                     file descriptor, and shall share any locks. The FD_CLOEXEC flag  associated  with  the  new
                     file  descriptor  shall  be  cleared  to keep the file open across calls to one of the exec
                     functions.

       F_DUPFD_CLOEXEC
                     Like F_DUPFD, but the FD_CLOEXEC flag associated with the new file descriptor shall be set.

       F_GETFD       Get the file descriptor flags defined in  <fcntl.h>  that  are  associated  with  the  file
                     descriptor  fildes.  File descriptor flags are associated with a single file descriptor and
                     do not affect other file descriptors that refer to the same file.

       F_SETFD       Set the file descriptor flags defined in <fcntl.h>, that are associated with fildes, to the
                     third argument, arg, taken as type int.  If the FD_CLOEXEC flag in the third argument is 0,
                     the file descriptor shall remain open  across  the  exec  functions;  otherwise,  the  file
                     descriptor shall be closed upon successful execution of one of the exec functions.

       F_GETFL       Get  the  file  status  flags  and  file  access  modes, defined in <fcntl.h>, for the file
                     description associated with fildes.  The file access modes can be extracted from the return
                     value  using the mask O_ACCMODE, which is defined in <fcntl.h>.  File status flags and file
                     access modes are associated with  the  file  description  and  do  not  affect  other  file
                     descriptors  that  refer  to the same file with different open file descriptions. The flags
                     returned may include non-standard file status flags which  the  application  did  not  set,
                     provided that these additional flags do not alter the behavior of a conforming application.

       F_SETFL       Set  the  file status flags, defined in <fcntl.h>, for the file description associated with
                     fildes from the corresponding bits in the third argument, arg, taken  as  type  int.   Bits
                     corresponding to the file access mode and the file creation flags, as defined in <fcntl.h>,
                     that are set in arg shall be ignored. If any bits in arg other than  those  mentioned  here
                     are  changed by the application, the result is unspecified. If fildes does not support non-
                     blocking operations, it is unspecified whether the O_NONBLOCK flag will be ignored.

       F_GETOWN      If fildes refers to a socket, get the process ID or process group ID specified  to  receive
                     SIGURG signals when out-of-band data is available. Positive values shall indicate a process
                     ID; negative values, other than -1, shall indicate a process group ID; the value zero shall
                     indicate  that  no SIGURG signals are to be sent. If fildes does not refer to a socket, the
                     results are unspecified.

       F_SETOWN      If fildes refers to a socket, set the process ID or process group ID specified  to  receive
                     SIGURG  signals  when out-of-band data is available, using the value of the third argument,
                     arg, taken as type int.  Positive values shall indicate  a  process  ID;  negative  values,
                     other  than  -1,  shall  indicate a process group ID; the value zero shall indicate that no
                     SIGURG signals are to be sent. Each time a SIGURG signal is sent to the  specified  process
                     or  process  group,  permission  checks  equivalent  to  those performed by kill() shall be
                     performed, as if kill() were called by a process with the same real user ID, effective user
                     ID,  and  privileges  that  the process calling fcntl() has at the time of the call; if the
                     kill() call would fail, no signal shall be  sent.  These  permission  checks  may  also  be
                     performed  by  the  fcntl()  call. If the process specified by arg later terminates, or the
                     process group specified by arg later becomes empty, while still being specified to  receive
                     SIGURG  signals  when  out-of-band  data is available from fildes, then no signals shall be
                     sent to any subsequently created process that has the same process ID or process group  ID,
                     regardless of permission; it is unspecified whether this is achieved by the equivalent of a
                     fcntl(fildes, F_SETOWN, 0) call at the time the process terminates or is waited for or  the
                     process  group  becomes empty, or by other means. If fildes does not refer to a socket, the
                     results are unspecified.

       The following values for cmd are available for advisory record locking. Record locking shall be supported
       for regular files, and may be supported for other files.

       F_GETLK       Get any lock which blocks the lock description pointed to by the third argument, arg, taken
                     as a pointer to type struct flock, defined in <fcntl.h>.  The information  retrieved  shall
                     overwrite  the  information  passed to fcntl() in the structure flock.  If no lock is found
                     that would prevent this lock from being created, then the structure shall be left unchanged
                     except for the lock type which shall be set to F_UNLCK.

       F_SETLK       Set  or clear a file segment lock according to the lock description pointed to by the third
                     argument, arg, taken as a pointer to type struct flock, defined in <fcntl.h>.  F_SETLK  can
                     establish shared (or read) locks (F_RDLCK) or exclusive (or write) locks (F_WRLCK), as well
                     as to remove either type of lock (F_UNLCK). F_RDLCK, F_WRLCK, and F_UNLCK  are  defined  in
                     <fcntl.h>.   If  a shared or exclusive lock cannot be set, fcntl() shall return immediately
                     with a return value of -1.

       F_SETLKW      This command shall be equivalent to F_SETLK except that if a shared or  exclusive  lock  is
                     blocked  by  other  locks,  the  thread shall wait until the request can be satisfied. If a
                     signal that is to be caught is received while fcntl() is  waiting  for  a  region,  fcntl()
                     shall  be  interrupted.  Upon  return from the signal handler, fcntl() shall return -1 with
                     errno set to [EINTR], and the lock operation shall not be done.

       Additional implementation-defined values for cmd may be defined in <fcntl.h>.  Their  names  shall  start
       with F_.

       When  a  shared  lock is set on a segment of a file, other processes shall be able to set shared locks on
       that segment or a portion of it. A shared lock prevents any other process from setting an exclusive  lock
       on  any  portion of the protected area. A request for a shared lock shall fail if the file descriptor was
       not opened with read access.

       An exclusive lock shall prevent any other process from setting a shared lock or an exclusive lock on  any
       portion  of the protected area. A request for an exclusive lock shall fail if the file descriptor was not
       opened with write access.

       The structure flock describes the type (l_type), starting offset (l_whence), relative  offset  (l_start),
       size (l_len), and process ID (l_pid) of the segment of the file to be affected.

       The  value  of  l_whence is SEEK_SET, SEEK_CUR, or SEEK_END, to indicate that the relative offset l_start
       bytes shall be measured from the start of the file, current position, or end of the  file,  respectively.
       The  value  of  l_len is the number of consecutive bytes to be locked. The value of l_len may be negative
       (where the definition of off_t permits negative values of l_len).  The l_pid  field  is  only  used  with
       F_GETLK  to  return  the  process  ID  of the process holding a blocking lock. After a successful F_GETLK
       request, when a blocking lock is found, the values returned in the flock structure shall be as follows:

       l_type    Type of blocking lock found.

       l_whence  SEEK_SET.

       l_start   Start of the blocking lock.

       l_len     Length of the blocking lock.

       l_pid     Process ID of the process that holds the blocking lock.

       If the command is F_SETLKW and the process must wait for another process to  release  a  lock,  then  the
       range  of  bytes to be locked shall be determined before the fcntl() function blocks. If the file size or
       file descriptor seek offset change while fcntl() is blocked, this shall not affect  the  range  of  bytes
       locked.

       If  l_len  is positive, the area affected shall start at l_start and end at l_start+l_len-1.  If l_len is
       negative, the area affected shall start at l_start+l_len and end  at  l_start-1.   Locks  may  start  and
       extend  beyond  the  current end of a file, but shall not extend before the beginning of the file. A lock
       shall be set to extend to the largest possible value of the file offset for that file by setting l_len to
       0.  If  such  a  lock  also has l_start set to 0 and l_whence is set to SEEK_SET, the whole file shall be
       locked.

       There shall be at most one type of lock set for each byte in the file.  Before a successful  return  from
       an  F_SETLK or an F_SETLKW request when the calling process has previously existing locks on bytes in the
       region specified by the request, the previous lock type for each byte in the specified  region  shall  be
       replaced  by  the  new lock type. As specified above under the descriptions of shared locks and exclusive
       locks, an F_SETLK or an F_SETLKW request (respectively) shall fail or  block  when  another  process  has
       existing  locks  on  bytes  in the specified region and the type of any of those locks conflicts with the
       type specified in the request.

       All locks associated with a file for a given process shall be removed when a  file  descriptor  for  that
       file  is  closed  by  that  process or the process holding that file descriptor terminates. Locks are not
       inherited by a child process.

       A potential for deadlock occurs if a process controlling a locked region is put to sleep by attempting to
       lock  the  locked region of another process. If the system detects that sleeping until a locked region is
       unlocked would cause a deadlock, fcntl() shall fail with an [EDEADLK] error.

       An unlock (F_UNLCK) request in which l_len is non-zero and the offset of the last byte of  the  requested
       segment  is the maximum value for an object of type off_t, when the process has an existing lock in which
       l_len is 0 and which includes the last byte of the requested segment, shall be treated as  a  request  to
       unlock  from  the start of the requested segment with an l_len equal to 0. Otherwise, an unlock (F_UNLCK)
       request shall attempt to unlock only the requested segment.

       When the file descriptor fildes refers to a shared memory object, the behavior of fcntl()  shall  be  the
       same  as  for  a  regular  file  except  the effect of the following values for the argument cmd shall be
       unspecified: F_SETFL, F_GETLK, F_SETLK, and F_SETLKW.

       If fildes refers to a typed memory object, the result of the fcntl() function is unspecified.

RETURN VALUE

       Upon successful completion, the value returned shall depend on cmd as follows:

       F_DUPFD     A new file descriptor.

       F_DUPFD_CLOEXEC
                   A new file descriptor.

       F_GETFD     Value of flags defined in <fcntl.h>.  The return value shall not be negative.

       F_SETFD     Value other than -1.

       F_GETFL     Value of file status flags and access modes. The return value is not negative.

       F_SETFL     Value other than -1.

       F_GETLK     Value other than -1.

       F_SETLK     Value other than -1.

       F_SETLKW    Value other than -1.

       F_GETOWN    Value of the socket owner process or process group; this will not be -1.

       F_SETOWN    Value other than -1.

       Otherwise, -1 shall be returned and errno set to indicate the error.

ERRORS

       The fcntl() function shall fail if:

       EACCES or EAGAIN
              The cmd argument is F_SETLK; the type  of  lock  (l_type)  is  a  shared  (F_RDLCK)  or  exclusive
              (F_WRLCK)  lock  and  the  segment  of  a file to be locked is already exclusive-locked by another
              process, or the type is an exclusive lock and some portion of the segment of a file to  be  locked
              is already shared-locked or exclusive-locked by another process.

       EBADF  The  fildes  argument  is  not  a  valid  open  file descriptor, or the argument cmd is F_SETLK or
              F_SETLKW, the type of lock, l_type, is a shared lock (F_RDLCK), and fildes is  not  a  valid  file
              descriptor  open  for  reading,  or  the type of lock, l_type, is an exclusive lock (F_WRLCK), and
              fildes is not a valid file descriptor open for writing.

       EINTR  The cmd argument is F_SETLKW and the function was interrupted by a signal.

       EINVAL The cmd argument is invalid, or the cmd argument is F_DUPFD or F_DUPFD_CLOEXEC and arg is negative
              or  greater  than or equal to {OPEN_MAX}, or the cmd argument is F_GETLK, F_SETLK, or F_SETLKW and
              the data pointed to by arg is not valid, or fildes refers to a file that does not support locking.

       EMFILE The argument cmd is F_DUPFD or F_DUPFD_CLOEXEC and all file descriptors available to  the  process
              are currently open, or no file descriptors greater than or equal to arg are available.

       ENOLCK The  argument cmd is F_SETLK or F_SETLKW and satisfying the lock or unlock request would result in
              the number of locked regions in the system exceeding a system-imposed limit.

       EOVERFLOW
              One of the values to be returned cannot be represented correctly.

       EOVERFLOW
              The cmd argument is F_GETLK, F_SETLK, or F_SETLKW and the smallest or, if l_len is  non-zero,  the
              largest  offset  of any byte in the requested segment cannot be represented correctly in an object
              of type off_t.

       ESRCH  The cmd argument is F_SETOWN and no process or process group can be found  corresponding  to  that
              specified by arg.

       The fcntl() function may fail if:

       EDEADLK
              The  cmd argument is F_SETLKW, the lock is blocked by a lock from another process, and putting the
              calling process to sleep to wait for that lock to become free would cause a deadlock.

       EINVAL The cmd argument is F_SETOWN and the value of the argument is not valid as a  process  or  process
              group identifier.

       EPERM  The  cmd  argument  is  F_SETOWN and the calling process does not have permission to send a SIGURG
              signal to any process specified by arg.

       The following sections are informative.

EXAMPLES

   Locking and Unlocking a File
       The following example demonstrates how to place a lock on bytes 100 to 109  of  a  file  and  then  later
       remove  it.  F_SETLK  is used to perform a non-blocking lock request so that the process does not have to
       wait if an incompatible lock is held by another process; instead the process can take some other action.

           #include <stdlib.h>
           #include <unistd.h>
           #include <fcntl.h>
           #include <errno.h>
           #include <stdio.h>

           int
           main(int argc, char *argv[])
           {
               int fd;
               struct flock fl;

               fd = open("testfile", O_RDWR);
               if (fd == -1)
                   /* Handle error */;

               /* Make a non-blocking request to place a write lock
                  on bytes 100-109 of testfile */

               fl.l_type = F_WRLCK;
               fl.l_whence = SEEK_SET;
               fl.l_start = 100;
               fl.l_len = 10;

               if (fcntl(fd, F_SETLK, &fl) == -1) {
                   if (errno == EACCES || errno == EAGAIN) {
                       printf("Already locked by another process\n");

                       /* We cannot get the lock at the moment */

                   } else {
                       /* Handle unexpected error */;
                   }
               } else { /* Lock was granted... */

                   /* Perform I/O on bytes 100 to 109 of file */

                   /* Unlock the locked bytes */

                   fl.l_type = F_UNLCK;
                   fl.l_whence = SEEK_SET;
                   fl.l_start = 100;
                   fl.l_len = 10;
                   if (fcntl(fd, F_SETLK, &fl) == -1)
                       /* Handle error */;
               }
               exit(EXIT_SUCCESS);
           } /* main */

   Setting the Close-on-Exec Flag
       The following example demonstrates how to set the close-on-exec flag for the file descriptor fd.

           #include <unistd.h>
           #include <fcntl.h>
           ...
               int flags;

               flags = fcntl(fd, F_GETFD);
               if (flags == -1)
                   /* Handle error */;
               flags |= FD_CLOEXEC;
               if (fcntl(fd, F_SETFD, flags) == -1)
                   /* Handle error */;"

APPLICATION USAGE

       The arg values to F_GETFD, F_SETFD, F_GETFL, and F_SETFL all represent flag values to  allow  for  future
       growth.  Applications  using these functions should do a read-modify-write operation on them, rather than
       assuming that only the values defined by this volume of POSIX.1‐2017 are valid. It is a common  error  to
       forget  this,  particularly in the case of F_SETFD. Some implementations set additional file status flags
       to advise the application of default behavior, even though the application did not request these flags.

       On systems which do not perform permission checks at the time of an fcntl() call with  F_SETOWN,  if  the
       permission  checks  performed  at the time the signal is sent disallow sending the signal to any process,
       the process that called fcntl() has no way of discovering that this has happened. A call to  kill()  with
       signal  0 can be used as a prior check of permissions, although this is no guarantee that permission will
       be granted at the time a signal is sent, since the target process(es) could change user IDs or privileges
       in the meantime.

RATIONALE

       The  ellipsis  in  the  SYNOPSIS  is  the syntax specified by the ISO C standard for a variable number of
       arguments. It is used because System V uses pointers for the implementation of file locking functions.

       This volume of POSIX.1‐2017 permits concurrent read and write access  to  file  data  using  the  fcntl()
       function;  this  is  a  change from the 1984 /usr/group standard and early proposals. Without concurrency
       controls, this feature may not be fully utilized without occasional loss of data.

       Data losses occur in several ways. One case occurs when several processes try to update the same  record,
       without sequencing controls; several updates may occur in parallel and the last writer ``wins''.  Another
       case is a bit-tree or other internal list-based  database  that  is  undergoing  reorganization.  Without
       exclusive use to the tree segment by the updating process, other reading processes chance getting lost in
       the database when the index blocks are split, condensed, inserted, or deleted. While  fcntl()  is  useful
       for  many  applications, it is not intended to be overly general and does not handle the bit-tree example
       well.

       This facility is only required for regular files because it is not appropriate for many devices  such  as
       terminals and network connections.

       Since  fcntl()  works with ``any file descriptor associated with that file, however it is obtained'', the
       file descriptor may have been inherited through a fork() or exec operation and thus  may  affect  a  file
       that another process also has open.

       The  use of the open file description to identify what to lock requires extra calls and presents problems
       if several processes are sharing an open file description, but there are too many implementations of  the
       existing mechanism for this volume of POSIX.1‐2017 to use different specifications.

       Another consequence of this model is that closing any file descriptor for a given file (whether or not it
       is the same open file description that created the lock) causes the locks on that file to be relinquished
       for  that process. Equivalently, any close for any file/process pair relinquishes the locks owned on that
       file for that process. But note that while an open file description may be shared through  fork(),  locks
       are not inherited through fork().  Yet locks may be inherited through one of the exec functions.

       The  identification  of  a  machine  in  a  network  environment  is  outside the scope of this volume of
       POSIX.1‐2017. Thus, an l_sysid member, such as found  in  System  V,  is  not  included  in  the  locking
       structure.

       Changing of lock types can result in a previously locked region being split into smaller regions.

       Mandatory locking was a major feature of the 1984 /usr/group standard.

       For advisory file record locking to be effective, all processes that have access to a file must cooperate
       and use the advisory mechanism before doing I/O on the file. Enforcement-mode record locking is important
       when it cannot be assumed that all processes are cooperating.  For example, if one user uses an editor to
       update a file at the same time that a second user executes another process that updates the same file and
       if  only  one  of  the  two  processes  is  using  advisory  locking,  the processes are not cooperating.
       Enforcement-mode record locking would protect against accidental collisions.

       Secondly, advisory record locking requires a process using locking to bracket  each  I/O  operation  with
       lock  (or test) and unlock operations.  With enforcement-mode file and record locking, a process can lock
       the file once and unlock when all I/O operations have been completed.   Enforcement-mode  record  locking
       provides  a  base that can be enhanced; for example, with sharable locks. That is, the mechanism could be
       enhanced to allow a process to lock a file so other processes could read it, but none of them could write
       it.

       Mandatory locks were omitted for several reasons:

        1. Mandatory  lock  setting  was done by multiplexing the set-group-ID bit in most implementations; this
           was confusing, at best.

        2. The relationship to file truncation as supported in 4.2 BSD was not well specified.

        3. Any publicly readable file could be locked  by  anyone.  Many  historical  implementations  keep  the
           password  database  in a publicly readable file. A malicious user could thus prohibit logins. Another
           possibility would be to hold open a long-distance telephone line.

        4. Some demand-paged historical implementations offer memory mapped files,  and  enforcement  cannot  be
           done on that type of file.

       Since  sleeping  on  a  region  is  interrupted with any signal, alarm() may be used to provide a timeout
       facility in applications requiring it. This is useful in deadlock detection. Since implementation of full
       deadlock detection is not always feasible, the [EDEADLK] error was made optional.

FUTURE DIRECTIONS

       None.

SEE ALSO

       alarm(), close(), exec, kill(), open(), sigaction()

       The Base Definitions volume of POSIX.1‐2017, <fcntl.h>, <signal.h>

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard
       for Information  Technology  --  Portable  Operating  System  Interface  (POSIX),  The  Open  Group  Base
       Specifications  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics
       Engineers, Inc and The Open Group.  In the event of any discrepancy between this version and the original
       IEEE  and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document.
       The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are most likely to have  been  introduced
       during   the   conversion  of  the  source  files  to  man  page  format.  To  report  such  errors,  see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .