Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

fcntl(3HEAD)

Name

fcntl.h, fcntl - file control options

Synopsis

#include <fcntl.h> 

Description

The <fcntl.h> header defines the following requests and arguments for use by the functions fcntl(2), open(2), and openat(2).

Values for cmd used by fcntl() (the following values are unique):

F_DUPFD

Duplicate file descriptor.

F_DUPFD_CLOEXEC

Duplicate file descriptor with the close-on-exec flag FD_CLOEXEC set.

F_DUPFD_CLOFORK

Duplicate file descriptor with the close-on-fork flag FD_CLOFORK set.

F_DUP2FD

Similar to F_DUPFD, but always returns arg.

F_DUP2FD_CLOEXEC

Similar to F_DUP2FD, but with the close-on-exec flag FD_CLOEXEC set.

F_DUP2FD_CLOFORK

Similar to F_DUP2FD, but with the close-on-fork flag FD_CLOFORK set.

F_DUP3FD

Similar to F_DUP2FD but allows a fourth argument.

F_GETFD

Get file descriptor flags.

F_SETFD

Set file descriptor flags.

F_GETFL

Get file status flags.

F_SETFL

Set file status flags.

F_GETOWN

Get process or process group ID to receive SIGURG signals.

F_SETOWN

Set process or process group ID to receive SIGURG signals.

F_FREESP

Free storage space associated with a section of the ordinary file fildes.

F_ALLOCSP

Allocate space for a section of the ordinary file fildes.

F_ALLOCSP64

Equivalent to F_ALLOCSP, but takes a struct flock64 argument rather than a struct flock argument.

F_GETLK

Get record locking information.

F_GETLK64

Equivalent to F_GETLK, but takes a struct flock64 argument rather than a struct flock argument.

F_SETLK

Set record locking information.

F_SETLK64

Equivalent to F_SETLK, but takes a struct flock64 argument rather than a struct flock argument.

F_SETLKW

Set record locking information; wait if blocked.

F_SETLKW64

Equivalent to F_SETLKW, but takes a struct flock64 argument rather than a struct flock argument.

F_SHARE

Set share reservation.

F_UNSHARE

Remove share reservation.

File descriptor flags used for fcntl():

FD_CLOEXEC

Close the file descriptor upon execution of an exec function (see exec(2)).

FD_CLOFORK

The file descriptor is no longer valid upon execution of a fork function (see fork(2)).

Values for l_type used for record locking with fcntl() (the following values are unique):

F_RDLCK

Shared or read lock.

F_UNLCK

Unlock.

F_WRLCK

Exclusive or write lock.

Values for f_access used for share reservations with fcntl() (the following values are unique):

F_RDACC

Read-only share reservation.

F_WRACC

Write-only share reservation.

F_RWACC

Read and write share reservation.

Values for f_deny used for share reservations with fcntl() (the following values are unique):

F_COMPAT

Compatibility mode share reservation.

F_RDDNY

Deny other read access share reservations.

F_WRDNY

Deny other write access share reservations.

F_RWDNY

Deny other read or write access share reservations.

F_NODNY

Do not deny other read or write access share reservations.

File creation and assignment flags are used in the oflag argument by open() and openat(). All of these values are bitwise distinct:

O_CREAT

Create file if it does not exist.

O_EXCL

Exclusive use flag.

O_NOCTTY

Do not assign controlling tty.

O_TRUNC

Truncate flag.

O_TTY_INIT

Set terminal parameters to have conforming behavior.

O_XATTR

When opening a file, this flag affects the way in which relative paths are resolved by open() and openat(). With this flag set, the path argument is resolved as an extended attribute reference on either the current working directory (if open) or of the file referenced by the file descriptor argument of openat().

O_NOSIGPIPE

Return EPIPE instead of sending a SIGPIPE.

File status flags used for fcntl(), open(), and open():

O_APPEND

Set append mode.

O_NDELAY

Non-blocking mode.

O_NONBLOCK

Non-blocking mode (POSIX; see standards(7)).

O_DSYNC

Write I/O operations on the file descriptor complete as defined by synchronized I/O data integrity completion.

O_RSYNC

Read I/O operations on the file descriptor complete at the same level of integrity as specified by the O_DSYNC and O_SYNC flags. If both O_DSYNC and O_RSYNC are set in oflag, all I/O operations on the file descriptor complete as defined by synchronized I/O data integrity completion. If both O_SYNC and O_RSYNC are set in oflag, all I/O operations on the file descriptor complete as defined by synchronized I/O file integrity completion.

O_SYNC

When opening a regular file, this flag affects subsequent writes. If set, each write(2) will wait for both the file data and file status to be physically updated. Write I/O operations on the file descriptor complete as defined by synchronized I/O file integrity completion.

Mask for use with file access modes:

O_ACCMODE

Mask for file access modes.

File access modes used for fcntl(), open(), and openat():

O_EXEC

Open ordinary file for execute only.

O_RDONLY

Open for reading only.

O_RDWR

Open for reading and writing.

O_SEARCH

Open directory for search only.

O_WRONLY

Open for writing only.

The following constants are used by system calls capable of resolving paths relative to a provided open file descriptor:

AT_FDCWD

Special value to pass in place of a file descriptor to inform the called routine that relative path arguments should be resolved from the current working directory.

The following constant is a value to be used for the flag passed to faccessat():

AT_EACCESS

Check access using effective user and group ID.

The following constant is a value to be used for the flag passed to fstatat(), fchmodat(), fchownat(), and utimensat():

AT_SYMLINK_NOFOLLOW

Do not follow symbolic links. In this case the functions operate on the symbolic link file rather than the file the link references.

The following constant is a value to be used for the flag passed to linkat():

AT_SYMLINK_FOLLOW

Follow symbolic link.

The following constants are values to be used for the oflag passed to open() and openat():

O_CLOEXEC

Set the FD_CLOEXEC flag on the new file descriptor.

O_CLOFORK

Set the FD_CLOFORK flag on the new file descriptor.

O_DIRECTORY

Fail if not a directory.

O_NOFOLLOW

Do not follow symbolic links.

The following constant is a value to be used for the flag passed to unlinkat():

AT_REMOVEDIR

Remove directory instead of file.

The flock structure describes a file lock. It includes the following members:

short   l_type;   /* Type of lock */
short   l_whence; /* Flag for starting offset */
off_t   l_start;  /* Relative offset in bytes */
off_t   l_len;    /* Size; if 0 then until EOF */
long    l_sysid;  /* Returned with F_GETLK */
pid_t   l_pid;    /* Returned with F_GETLK */

The structure fshare describes a file share reservation. It includes the following members:

short   f_access; /* Type of reservation */
short   f_deny;   /* Type of reservations to deny */
long    f_id;     /* Process unique identifier */

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
Standard

See Also

creat(2), exec(2), fcntl(2), open(2), fdatasync(3C), fsync(3C), attributes(7), fsattr(7), standards(7)

Notes

Data is successfully transferred for a write operation to a regular file when the system ensures that all data written is readable on any subsequent open of the file (even one that follows a system or power failure) in the absence of a failure of the physical storage medium.

Data is successfully transferred for a read operation when an image of the data on the physical storage medium is available to the requesting process.

Synchronized I/O data integrity completion (see fdatasync(3C)):

  • For reads, the operation has been completed or diagnosed if unsuccessful. The read is complete only when an image of the data has been successfully transferred to the requesting process. If there were any pending write requests affecting the data to be read at the time that the synchronized read operation was requested, these write requests will be successfully transferred prior to reading the data.

  • For writes, the operation has been completed or diagnosed if unsuccessful. The write is complete only when the data specified in the write request is successfully transferred, and all file system information required to retrieve the data is successfully transferred.

File attributes that are not necessary for data retrieval (access time, modification time, status change time) need not be successfully transferred prior to returning to the calling process.

Synchronized I/O file integrity completion (see fsync(3C)):

  • Identical to a synchronized I/O data integrity completion with the addition that all file attributes relative to the I/O operation (including access time, modification time, status change time) will be successfully transferred prior to returning to the calling process.