# fcntl

## 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.
    


* * *