fcntl(3p) — Linux manual page

PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

FCNTL(3P)               POSIX Programmer's Manual              FCNTL(3P)

PROLOG         top

       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         top

       fcntl — file control

SYNOPSIS         top

       #include <fcntl.h>

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

DESCRIPTION         top

       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         top

       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         top

       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         top

   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         top

       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         top

       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         top

       None.

SEE ALSO         top

       alarm(3p), close(3p), exec(1p), kill(3p), open(3p), sigaction(3p)

       The Base Definitions volume of POSIX.1‐2017, fcntl.h(0p),
       signal.h(0p)

COPYRIGHT         top

       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:https://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 .

IEEE/The Open Group               2017                         FCNTL(3P)

Pages that refer to this page: fcntl.h(0p)stropts.h(0p)aio_fsync(3p)dup(3p)exec(3p)fchmod(3p)fdatasync(3p)fork(3p)fstatvfs(3p)ioctl(3p)lockf(3p)mmap(3p)open(3p)pipe(3p)posix_spawn(3p)posix_typed_mem_open(3p)pselect(3p)read(3p)shm_open(3p)write(3p)