Controls open file descriptors.
Standard C Library (libc.a)
Berkeley compatibility library (libbsd.a) (for the fcntl subroutine)
#include <fcntl.h>
int fcntl ( FileDescriptor, Command, Argument) int FileDescriptor, Command, Argument;
#include <unistd.h>
int dup2( Old, New) int Old, New;
int dup( FileDescriptor) int FileDescriptor;
The fcntl subroutine performs controlling operations on the open file specified by the FileDescriptor parameter. If Network File System (NFS) is installed on your system, the open file can reside on another node. The fcntl subroutine is used to:
The fcntl subroutine can provide the same functions as the dup and dup2 subroutines.
If FileDescriptor refers to a terminal device or socket, then asynchronous I/O facilities can be used. These facilities are normally enabled by using the ioctl subroutine with the FIOASYNC, FIOSETOWN, and FIOGETOWN commands. However, a BSD-compatible mechanism is also available if the application is linked with the libbsd.a library.
When the FileDescriptor parameter refers to a shared memory object, the fcntl subroutine manages only the F_DUPFD, F_DUP2FD, F_GETFD, F_SETFD, F_GETFL, and F_CLOSEM commands.
When using the libbsd.a library, asynchronous I/O is enabled by using the F_SETFL command with the FASYNC flag set in the Argument parameter. The F_GETOWN and F_SETOWN commands get the current asynchronous I/O owner and set the asynchronous I/O owner. However, these commands are valid only when the file descriptor refers to a terminal device or a socket.
All applications containing the fcntl subroutine must be complied with _BSD set to a specific value. Acceptable values are 43 and 44. In addition, all socket applications must include the BSD libbsd.a library.
General Record Locking Information
A lock is either an enforced or advisory lock and either a read or a write lock.
Attention: Buffered I/O does not work properly when used with file locking. Do not use the standard I/O package routines on files that are going to be locked.
For a lock to be an enforced lock, the Enforced Locking attribute of the file must be set; for example, the S_ENFMT bit must be set, but the S_IXGRP, S_IXUSR, and S_IXOTH bits must be clear. Otherwise, the lock is an advisory lock. A given file can have advisory or enforced locks, but not both. The description of the sys/mode.h file includes a description of file attributes.
When a process holds an enforced lock on a section of a file, no other process can access that section of the file with the read or write subroutine. In addition, the open (open, openat, openx, openxat, open64, open64at, open64x, open64xat, creat, or creat64 Subroutine) and ftruncate subroutines cannot truncate the locked section of the file, and the fclear (fclear or fclear64 Subroutine) subroutine cannot modify the locked section of the file. If another process attempts to read or modify the locked section of the file, the process either sleeps until the section is unlocked or returns with an error indication.
When a process holds an advisory lock on a section of a file, no other process can lock that section of the file (or an overlapping section) with the fcntl subroutine. (No other subroutines are affected.) As a result, processes must voluntarily call the fcntl subroutine in order to make advisory locks effective.
When a process holds a read lock on a section of a file, other processes can also set read locks on that section or on subsets of it. Read locks are also called shared locks.
A read lock prevents any other process from setting a write lock on any part of the protected area. If the read lock is also an enforced lock, no other process can modify the protected area.
The file descriptor on which a read lock is being placed must have been opened with read access.
When a process holds a write lock on a section of a file, no other process can set a read lock or a write lock on that section. Write locks are also called exclusive locks. Only one write lock and no read locks can exist for a specific section of a file at any time.
If the lock is also an enforced lock, no other process can read or modify the protected area.
The following general rules about file locking apply:
Locks can start and extend beyond the current end of a file but cannot be negative relative to the beginning of the file. A lock can be set to extend to the end of the file by setting the l_len field to 0. If such a lock also has the l_start and l_whence fields set to 0, the whole file is locked. The l_len, l_start, and l_whence locking fields are part of the flock structure.
When an application locks a region of a file using the 32 bit locking interface (F_SETLK), and the last byte of the lock range includes MAX_OFF (2 Gb - 1), then the lock range for the unlock request will be extended to include MAX_END (2 ^ ^ 63 - 1).
| Item | Description |
|---|---|
| FileDescriptor | Specifies an open file descriptor obtained from a successful call to the open subroutine, fcntl subroutine, pipe subroutine, or shm_open subroutine. File descriptors are small positive integers used (instead offile names) to identify files or a shared memory object. |
| Argument | Specifies a variable whose value sets the function specified by the Command parameter. When dealing with file locks, the Argument parameter must be a pointer to the FLOCK structure. |
| Command | Specifies the operation performed by the fcntl subroutine. The fcntl subroutine can duplicate open file descriptors, set file-descriptor flags, set file descriptor locks, set process IDs, and close open file descriptors. |
Duplicating File Descriptors
| Item | Description |
|---|---|
| F_DUPFD | Returns a new file descriptor as follows:
|
Setting File-Descriptor Flags
| Item | Description |
|---|---|
| F_GETFD | Gets the close-on-exec flag (FD_CLOEXEC bit) that is associated with the file descriptor specified by the FileDescriptor parameter. The Argument parameter is ignored. File descriptor flags are associated with a single file descriptor, and do not affect others associated with the same file. |
| F_SETFD | Assigns the value of the Argument parameter to the close-on-exec flag (FD_CLOEXEC bit) that is associated with the FileDescriptor parameter. If the FD_CLOEXEC flag value is 0, the file remains open across any calls to exec subroutines; otherwise, the file will close upon the successful execution of an exec subroutine. |
| F_GETFL | Gets the file-status flags and file-access modes for the
open file description associated with the file descriptor specified
by the FileDescriptor parameter. The open file description
is set at the time the file is opened and applies only to those file
descriptors associated with that particular call to the file. This
open file descriptor does not affect other file descriptors that refer
to the same file with different open file descriptions. The file-status flags have the following values:
The file-access modes have the following values:
The file access flags can be extracted from the return value using the O_ACCMODE mask, which is defined in the fcntl.h file. |
| F_SETFL | Sets the file status flags from the corresponding bits specified
by the Argument parameter. The file-status flags are set for
the open file description associated with the file descriptor specified
by the FileDescriptor parameter. The following flags may be
set:
The O_NDELAY and O_NONBLOCK flags affect only operations against file descriptors derived from the same open subroutine. In BSD, these operations apply to all file descriptors that refer to the object. |
Setting File Locks
| Item | Description |
|---|---|
| F_GETLK | Gets information on the first lock that blocks the lock described in the flock structure. The Argument parameter should be a pointer to a type struct flock, as defined in the flock.h file. The information retrieved by the fcntl subroutine overwrites the information in the struct flock pointed to by the Argument parameter. If no lock is found that would prevent this lock from being created, the structure is left unchanged, except for lock type (l_type) which is set to F_UNLCK. |
| F_SETLK | Sets or clears a file-segment lock according to the lock description pointed to by the Argument parameter. The Argument parameter should be a pointer to a type struct flock, which is defined in the flock.h file. The F_SETLK option is used to establish read (or shared) locks (F_RDLCK), or write (or exclusive) locks (F_WRLCK), as well as to remove either type of lock (F_UNLCK). The lock types are defined by the fcntl.h file. If a shared or exclusive lock cannot be set, the fcntl subroutine returns immediately. |
| F_SETLKW | Performs the same function as the F_SETLK option unless a read or write lock is blocked by existing locks, in which case the process sleeps until the section of the file is free to be locked. If a signal that is to be caught is received while the fcntl subroutine is waiting for a region, the fcntl subroutine is interrupted, returns a -1, sets the errno global variable to EINTR. The lock operation is not done. |
| Item | Description |
|---|---|
| F_GETLK64 | Gets information on the first lock that blocks the lock described in the flock64 structure. The Argument parameter should be a pointer to an object of the type struct flock64, as defined in the flock.h file. The information retrieved by the fcntl subroutine overwrites the information in the struct flock64 pointed to by the Argument parameter. If no lock is found that would prevent this lock from being created, the structure is left unchanged, except for lock type (l_type) which is set to F_UNLCK. |
| F_SETLK64 | Sets or clears a file-segment lock according to the lock description pointed to by the Argument parameter. The Argument parameter should be a pointer to a type struct flock64, which is defined in the flock.h file. The F_SETLK option is used to establish read (or shared) locks (F_RDLCK), or write (or exclusive) locks (F_WRLCK), as well as to remove either type of lock (F_UNLCK). The lock types are defined by the fcntl.h file. If a shared or exclusive lock cannot be set, the fcntl subroutine returns immediately. |
| F_SETLKW64 | Performs the same function as the F_SETLK option unless a read or write lock is blocked by existing locks, in which case the process sleeps until the section of the file is free to be locked. If a signal that is to be caught is received while the fcntl subroutine is waiting for a region, the fcntl subroutine is interrupted, returns a -1, sets the errno global variable to EINTR. The lock operation is not done. |
Setting Process ID
| Item | Description |
|---|---|
| F_GETOWN | Gets the process ID or process group currently receiving SIGIO and SIGURG signals. Process groups are returned as negative values. |
| F_SETOWN | Sets the process or process group to receive SIGIO and SIGURG signals. Process groups are specified by supplying a negative Argument value. Otherwise, the Argument parameter is interpreted as a process ID. |
Closing File Descriptors
| Item | Description |
|---|---|
| F_CLOSEM | Closes all file descriptors from FileDescriptor up to the number specified by the OPEN_MAX value. |
| Old | Specifies an open file descriptor. |
| New | Specifies an open file descriptor that is returned by the dup2 subroutine. |
The lockfx Subroutine
The fcntl subroutine functions similar to the lockfx subroutine, when the Command parameter is F_SETLK, F_SETLKW, or F_GETLK, and when used in the following way:
fcntl (FileDescriptor, Command, Argument)
is equivalent to:
lockfx (FileDescriptor, Command, Argument)
The dup and dup2 Subroutines
The fcntl subroutine functions similar to the dup and dup2 subroutines, when used in the following way:
dup (FileDescriptor)is equivalent to:
fcntl (FileDescriptor, F_DUPFD, 0)dup2 (Old, New)is equivalent to:
close (New);
fcntl(Old, F_DUPFD, New)The dup and dup2 subroutines differ from the fcntl subroutine in the following ways:
Upon successful completion, the value returned depends on the value of the Command parameter, as follows:
| Item | Description |
|---|---|
| Command | Return Value |
| F_DUPFD | A new file descriptor |
| F_GETFD | The value of the flag (only the FD_CLOEXEC bit is defined) |
| F_SETFD | A value other than -1 |
| F_GETFL | The value of file flags |
| F_SETFL | A value other than -1 |
| F_GETOWN | The value of descriptor owner |
| F_SETOWN | A value other than -1 |
| F_GETLK | A value other than -1 |
| F_SETLK | A value other than -1 |
| F_SETLKW | A value other than -1 |
| F_CLOSEM | A value other than -1. |
If the fcntl subroutine fails, a value of -1 is returned and the errno global variable is set to indicate the error.
The fcntl subroutine is unsuccessful if one or more of the following are true:
| Item | Description |
|---|---|
| EACCES | The Command argument is F_SETLK; the type of lock is a shared or exclusive lock and the segment of a file to be locked is already exclusively-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 FileDescriptor parameter is not a valid open file descriptor. |
| EDEADLK | The Command argument is F_SETLKW; the lock is blocked by some lock from another process and putting the calling process to sleep, waiting for that lock to become free would cause a deadlock. |
| ENOTTY | The file descriptor does not refer to a terminal device or socket. |
| EMFILE | The Command parameter is F_DUPFD, and the maximum number of file descriptors are currently open (OPEN_MAX). |
| EINVAL | The Command parameter is F_DUPFD, and the Argument parameter is negative or greater than or equal to OPEN_MAX. |
| EINVAL | An illegal value was provided for the Command parameter. |
| EINVAL | An attempt was made to lock a fifo or pipe. |
| ESRCH | The value of the Command parameter is F_SETOWN, and the process ID specified as the Argument parameter is not in use. |
| EINTR | The Command parameter was F_SETLKW and the process received a signal while waiting to acquire the lock. |
| EOVERFLOW | The Command parameter was F_GETLK and the block lock could not be represented in the flock structure. |
The dup and dup2 subroutines fail if one or both of the following are true:
| Item | Description |
|---|---|
| EBADF | The Old parameter specifies an invalid open file descriptor or the New parameter specifies a file descriptor that is out of range. |
| EMFILE | The number of file descriptors exceeds the OPEN_MAX value or there is no file descriptor above the value of the New parameter. |
If NFS is installed on the system, the fcntl subroutine can fail if the following is true:
| Item | Description |
|---|---|
| ETIMEDOUT | The connection timed out. |