fcntl.3p (24213B)
- '\" et
- .TH FCNTL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH 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.
- .\"
- .SH NAME
- fcntl
- \(em file control
- .SH SYNOPSIS
- .LP
- .nf
- #include <fcntl.h>
- .P
- int fcntl(int \fIfildes\fP, int \fIcmd\fP, ...);
- .fi
- .SH DESCRIPTION
- The
- \fIfcntl\fR()
- function shall perform the operations described below on open files. The
- .IR fildes
- argument is a file descriptor.
- .P
- The available values for
- .IR cmd
- are defined in
- .IR <fcntl.h>
- and are as follows:
- .IP F_DUPFD 14
- Return a new file descriptor which shall be allocated as described in
- .IR "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,
- .IR arg ,
- taken as an integer of type
- .BR 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
- .IR exec
- functions.
- .IP F_DUPFD_CLOEXEC 14
- .br
- Like F_DUPFD, but the FD_CLOEXEC flag associated with the new file
- descriptor shall be set.
- .IP F_GETFD 14
- Get the file descriptor flags defined in
- .IR <fcntl.h>
- that are associated with the file descriptor
- .IR fildes .
- File descriptor flags are associated with a single file descriptor and
- do not affect other file descriptors that refer to the same file.
- .IP F_SETFD 14
- Set the file descriptor flags defined in
- .IR <fcntl.h> ,
- that are associated with
- .IR fildes ,
- to the third argument,
- .IR arg ,
- taken as type
- .BR int .
- If the FD_CLOEXEC flag in the third argument
- is 0, the file descriptor shall remain open across the
- .IR exec
- functions; otherwise, the file descriptor shall be closed upon
- successful execution of one of the
- .IR exec
- functions.
- .IP F_GETFL 14
- Get the file status flags and file access modes, defined in
- .IR <fcntl.h> ,
- for the file description associated with
- .IR fildes .
- The file access modes can be extracted from the return value using the
- mask O_ACCMODE, which is defined in
- .IR <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.
- .IP F_SETFL 14
- Set the file status flags, defined in
- .IR <fcntl.h> ,
- for the file description associated with
- .IR fildes
- from the corresponding bits in the third argument,
- .IR arg ,
- taken as type
- .BR int .
- Bits corresponding to the file access mode and the file creation
- flags, as defined in
- .IR <fcntl.h> ,
- that are set in
- .IR arg
- shall be ignored. If any bits in
- .IR arg
- other than those mentioned here are changed by the application, the
- result is unspecified. If
- .IR fildes
- does not support non-blocking operations, it is unspecified whether the
- O_NONBLOCK flag will be ignored.
- .IP F_GETOWN 14
- If
- .IR 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
- .IR fildes
- does not refer to a socket, the results are unspecified.
- .IP F_SETOWN 14
- If
- .IR 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,
- .IR arg ,
- taken as type
- .BR 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
- \fIkill\fR()
- shall be performed, as if
- \fIkill\fR()
- were called by a process with the same real user ID, effective
- user ID, and privileges that the process calling
- \fIfcntl\fR()
- has at the time of the call; if the
- \fIkill\fR()
- call would fail, no signal shall be sent. These permission checks may
- also be performed by the
- \fIfcntl\fR()
- call. If the process specified by
- .IR arg
- later terminates, or the process group specified by
- .IR arg
- later becomes empty, while still being specified to receive
- SIGURG signals when out-of-band data is available from
- .IR 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
- .IR 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
- .IR fildes
- does not refer to a socket, the results are unspecified.
- .P
- The following values for
- .IR cmd
- are available for advisory record locking. Record locking shall be
- supported for regular files, and may be supported for other files.
- .IP F_GETLK 14
- Get any lock which blocks the lock description pointed to by the
- third argument,
- .IR arg ,
- taken as a pointer to type
- .BR "struct flock" ,
- defined in
- .IR <fcntl.h> .
- The information retrieved shall overwrite the information passed to
- \fIfcntl\fR()
- in the structure
- .BR 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.
- .IP F_SETLK 14
- Set or clear a file segment lock according to the lock description
- pointed to by the third argument,
- .IR arg ,
- taken as a pointer to type
- .BR "struct flock" ,
- defined in
- .IR <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
- .IR <fcntl.h> .
- If a shared or exclusive lock cannot be set,
- \fIfcntl\fR()
- shall return immediately with a return value of \-1.
- .IP F_SETLKW 14
- 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
- \fIfcntl\fR()
- is waiting for a region,
- \fIfcntl\fR()
- shall be interrupted. Upon return from the signal handler,
- \fIfcntl\fR()
- shall return \-1 with
- .IR errno
- set to
- .BR [EINTR] ,
- and the lock operation shall not be done.
- .P
- Additional implementation-defined values for
- .IR cmd
- may be defined in
- .IR <fcntl.h> .
- Their names shall start with F_.
- .P
- 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.
- .P
- 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.
- .P
- The structure
- .BR flock
- describes the type (\c
- .IR l_type ),
- starting offset (\c
- .IR l_whence ),
- relative offset (\c
- .IR l_start ),
- size (\c
- .IR l_len ),
- and process ID (\c
- .IR l_pid )
- of the segment of the file to be affected.
- .P
- The value of
- .IR l_whence
- is SEEK_SET, SEEK_CUR, or SEEK_END,
- to indicate that the relative offset
- .IR l_start
- bytes shall be measured from the start of the file, current position,
- or end of the file, respectively. The value of
- .IR l_len
- is the number of consecutive bytes to be locked. The value of
- .IR l_len
- may be negative (where the definition of
- .BR off_t
- permits negative values of
- .IR l_len ).
- The
- .IR 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
- .BR flock
- structure shall be as follows:
- .IP "\fIl_type\fP" 10
- Type of blocking lock found.
- .IP "\fIl_whence\fP" 10
- SEEK_SET.
- .IP "\fIl_start\fP" 10
- Start of the blocking lock.
- .IP "\fIl_len\fP" 10
- Length of the blocking lock.
- .IP "\fIl_pid\fP" 10
- Process ID of the process that holds the blocking lock.
- .P
- 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
- \fIfcntl\fR()
- function blocks. If the file size or file descriptor seek offset change
- while
- \fIfcntl\fR()
- is blocked, this shall not affect the range of bytes locked.
- .P
- If
- .IR l_len
- is positive, the area affected shall start at
- .IR l_start
- and end at
- .IR l_start +\c
- .IR l_len \-1.
- If
- .IR l_len
- is negative, the area affected shall start at
- .IR l_start +\c
- .IR l_len
- and end at
- .IR 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
- .IR l_len
- to 0. If such a lock also has
- .IR l_start
- set to 0 and
- .IR l_whence
- is set to SEEK_SET, the whole file shall be locked.
- .P
- 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.
- .P
- 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.
- .P
- 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,
- \fIfcntl\fR()
- shall fail with an
- .BR [EDEADLK]
- error.
- .P
- An unlock (F_UNLCK) request in which
- .IR 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
- .BR off_t ,
- when the process has an existing lock in which
- .IR 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
- .IR l_len
- equal to 0. Otherwise, an unlock (F_UNLCK) request shall attempt to
- unlock only the requested segment.
- .P
- When the file descriptor
- .IR fildes
- refers to a shared memory object, the behavior of
- \fIfcntl\fR()
- shall be the same as for a regular file except the effect of the
- following values for the argument
- .IR cmd
- shall be unspecified: F_SETFL, F_GETLK, F_SETLK, and F_SETLKW.
- .P
- If
- .IR fildes
- refers to a typed memory object, the result of the
- \fIfcntl\fR()
- function is unspecified.
- .SH "RETURN VALUE"
- Upon successful completion, the value returned shall depend on
- .IR cmd
- as follows:
- .IP F_DUPFD 12
- A new file descriptor.
- .IP F_DUPFD_CLOEXEC 12
- .br
- A new file descriptor.
- .IP F_GETFD 12
- Value of flags defined in
- .IR <fcntl.h> .
- The return value shall not be negative.
- .IP F_SETFD 12
- Value other than \-1.
- .IP F_GETFL 12
- Value of file status flags and access modes. The return value is not
- negative.
- .IP F_SETFL 12
- Value other than \-1.
- .IP F_GETLK 12
- Value other than \-1.
- .IP F_SETLK 12
- Value other than \-1.
- .IP F_SETLKW 12
- Value other than \-1.
- .IP F_GETOWN 12
- Value of the socket owner process or process group; this will not be
- \-1.
- .IP F_SETOWN 12
- Value other than \-1.
- .P
- Otherwise, \-1 shall be returned and
- .IR errno
- set to indicate the error.
- .SH ERRORS
- The
- \fIfcntl\fR()
- function shall fail if:
- .TP
- .BR EACCES " or " EAGAIN
- .br
- The
- .IR cmd
- argument is F_SETLK; the type of lock (\c
- .IR 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.
- .TP
- .BR EBADF
- The
- .IR fildes
- argument is not a valid open file descriptor, or the argument
- .IR cmd
- is F_SETLK or F_SETLKW, the type of lock,
- .IR l_type ,
- is a shared lock (F_RDLCK), and
- .IR fildes
- is not a valid file descriptor open for reading, or the type of lock,
- .IR l_type ,
- is an exclusive lock (F_WRLCK), and
- .IR fildes
- is not a valid file descriptor open for writing.
- .TP
- .BR EINTR
- The
- .IR cmd
- argument is F_SETLKW and the function was interrupted by a signal.
- .TP
- .BR EINVAL
- The
- .IR cmd
- argument is invalid, or the
- .IR cmd
- argument is F_DUPFD or F_DUPFD_CLOEXEC and
- .IR arg
- is negative or greater than or equal to
- {OPEN_MAX},
- or the
- .IR cmd
- argument is F_GETLK, F_SETLK, or F_SETLKW and the data pointed to by
- .IR arg
- is not valid, or
- .IR fildes
- refers to a file that does not support locking.
- .TP
- .BR EMFILE
- The argument
- .IR 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
- .IR arg
- are available.
- .TP
- .BR ENOLCK
- The argument
- .IR 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.
- .TP
- .BR EOVERFLOW
- One of the values to be returned cannot be represented correctly.
- .TP
- .BR EOVERFLOW
- The
- .IR cmd
- argument is F_GETLK, F_SETLK, or F_SETLKW and the smallest or, if
- .IR l_len
- is non-zero, the largest offset of any byte in the requested segment
- cannot be represented correctly in an object of type
- .BR off_t .
- .TP
- .BR ESRCH
- The
- .IR cmd
- argument is F_SETOWN and no process or process group can be found
- corresponding to that specified by
- .IR arg .
- .br
- .P
- The
- \fIfcntl\fR()
- function may fail if:
- .TP
- .BR EDEADLK
- The
- .IR 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.
- .TP
- .BR EINVAL
- The
- .IR cmd
- argument is F_SETOWN and the value of the argument is not valid as a
- process or process group identifier.
- .TP
- .BR EPERM
- The
- .IR cmd
- argument is F_SETOWN and the calling process does not have
- permission to send a SIGURG signal to any process specified by
- .IR arg .
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- .SS "Locking and Unlocking a File"
- .P
- 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.
- .sp
- .RS 4
- .nf
- #include <stdlib.h>
- #include <unistd.h>
- #include <fcntl.h>
- #include <errno.h>
- #include <stdio.h>
- .P
- int
- main(int argc, char *argv[])
- {
- int fd;
- struct flock fl;
- .P
- fd = open("testfile", O_RDWR);
- if (fd == -1)
- /* Handle error */;
- .P
- /* Make a non-blocking request to place a write lock
- on bytes 100-109 of testfile */
- .P
- fl.l_type = F_WRLCK;
- fl.l_whence = SEEK_SET;
- fl.l_start = 100;
- fl.l_len = 10;
- .P
- if (fcntl(fd, F_SETLK, &fl) == -1) {
- if (errno == EACCES || errno == EAGAIN) {
- printf("Already locked by another process\en");
- .P
- /* We cannot get the lock at the moment */
- .P
- } else {
- /* Handle unexpected error */;
- }
- } else { /* Lock was granted... */
- .P
- /* Perform I/O on bytes 100 to 109 of file */
- .P
- /* Unlock the locked bytes */
- .P
- 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 */
- .fi
- .P
- .RE
- .SS "Setting the Close-on-Exec Flag"
- .P
- The following example demonstrates how to set the close-on-exec flag
- for the file descriptor
- .IR fd .
- .sp
- .RS 4
- .nf
- #include <unistd.h>
- #include <fcntl.h>
- \&...
- int flags;
- .P
- flags = fcntl(fd, F_GETFD);
- if (flags == -1)
- /* Handle error */;
- flags |= FD_CLOEXEC;
- if (fcntl(fd, F_SETFD, flags) == -1)
- /* Handle error */;"
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- The
- .IR 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\(hy2017 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.
- .P
- On systems which do not perform permission checks at the time of an
- \fIfcntl\fR()
- 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
- \fIfcntl\fR()
- has no way of discovering that this has happened. A call to
- \fIkill\fR()
- 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.
- .SH 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.
- .P
- This volume of POSIX.1\(hy2017 permits concurrent read and write access to file data using the
- \fIfcntl\fR()
- 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.
- .P
- 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
- \fIfcntl\fR()
- is useful for many applications, it is not intended to be overly
- general and does not handle the bit-tree example well.
- .P
- This facility is only required for regular files because it is not
- appropriate for many devices such as terminals and network
- connections.
- .P
- Since
- \fIfcntl\fR()
- works with ``any file descriptor associated with that file, however it
- is obtained'', the file descriptor may have been inherited through a
- \fIfork\fR()
- or
- .IR exec
- operation and thus may affect a file that another process also has
- open.
- .P
- 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\(hy2017 to use different specifications.
- .P
- 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
- \fIfork\fR(),
- locks are not inherited through
- \fIfork\fR().
- Yet locks may be inherited through one of the
- .IR exec
- functions.
- .P
- The identification of a machine in a network environment is outside
- the scope of this volume of POSIX.1\(hy2017. Thus, an
- .IR l_sysid
- member, such as found in System V, is not included in the locking
- structure.
- .P
- Changing of lock types can result in a previously locked region being
- split into smaller regions.
- .P
- Mandatory locking was a major feature of the 1984 /usr/group standard.
- .P
- 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.
- .P
- 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.
- .P
- Mandatory locks were omitted for several reasons:
- .IP " 1." 4
- Mandatory lock setting was done by multiplexing the set-group-ID
- bit in most implementations; this was confusing, at best.
- .IP " 2." 4
- The relationship to file truncation as supported in 4.2 BSD
- was not well specified.
- .IP " 3." 4
- 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.
- .IP " 4." 4
- Some demand-paged historical implementations offer memory mapped files,
- and enforcement cannot be done on that type of file.
- .P
- Since sleeping on a region is interrupted with any signal,
- \fIalarm\fR()
- 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
- .BR [EDEADLK]
- error was made optional.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIalarm\fR\^(\|)",
- .IR "\fIclose\fR\^(\|)",
- .IR "\fIexec\fR\^",
- .IR "\fIkill\fR\^(\|)",
- .IR "\fIopen\fR\^(\|)",
- .IR "\fIsigaction\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<fcntl.h>\fP",
- .IR "\fB<signal.h>\fP"
- .\"
- .SH COPYRIGHT
- 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 .
- .PP
- 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 .