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 the lowest
                     numbered available (that is, not already open) 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 or
                     process group ID specified to receive SIGURG signals
                     when out-of-band data is available. Positive values
                     indicate a process ID; negative values, other than −1,
                     indicate a process group ID. If fildes does not refer
                     to a socket, the results are unspecified.

       F_SETOWN      If fildes refers to a socket, set the process 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 indicate a process ID; negative values, other
                     than −1, indicate a process group ID. 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 the first 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.

       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.

       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 can't 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‐2008 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.

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‐2008 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‐2008 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‐2008. 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), open(3p), sigaction(3p)

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

COPYRIGHT         top

       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information
       Technology -- Portable Operating System Interface (POSIX), The Open
       Group Base Specifications Issue 7, Copyright (C) 2013 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
       applied.) 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.unix.org/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                 2013                           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)