NAME

fcntl - file control

 SYNOPSIS

#include <sys/types.h>
#include <unistd.h>
#include <fcntl.h>

int fcntl(int fildes, int cmd, ...);

 DESCRIPTION

The fcntl() function provides for control over open files. The fildes argument is a file descriptor.

The available values for cmd are defined in the header <fcntl.h>, which include:

F_DUPFD

Return a new file descriptor which is 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 refers to the same open file description as the original file descriptor, and shares any locks. The FD_CLOEXEC flag associated with the new file descriptor is cleared to keep the file open across calls to one of the exec functions.

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 will remain open across the exec functions; otherwise the file will 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.

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 oflag values that are set in arg are ignored. If any bits in arg other than those mentioned here are changed by the application, the result is unspecified.

The following values for cmd are available for advisory record locking. Record locking is 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 overwrites 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 will be left unchanged except for the lock type which will 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 is used to 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() will return immediately with a return value of -1.

F_SETLKW

This command is the same as F_SETLK except that if a shared or exclusive lock is blocked by other locks, the thread will 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() will be interrupted. Upon return from the signal handler, fcntl() will return -1 with errno set to [EINTR], and the lock operation will not be done.

Additional implementation-dependent values for cmd may be defined in <fcntl.h>. Their names will start with F_.

When a shared lock is set on a segment of a file, other processes will 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 will fail if the file descriptor was not opened with read access.

An exclusive lock will 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 will 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 will 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, that is, one in which a lock was found, the value of l_whence will be SEEK_SET.

If l_len is positive, the area affected starts at l_start and ends at l_start + l_len-1. If l_len is negative, the area affected starts at l_start + l_len and ends at l_start-1. Locks may start and extend beyond the current end of a file, but must not be negative relative to the beginning of the file. A lock will 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 will be locked.

There will 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 will 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 will (respectively) 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 are 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 created using fork().

A potential for deadlock occurs if a process controlling a locked region is put to sleep by attempting to lock another process' locked region. If the system detects that sleeping until a locked region is unlocked would cause a deadlock, fcntl() will fail with an [EDEADLK] error.

If _XOPEN_REALTIME is defined and has a value other than -1:

When the file descriptor fildes refers to a shared memory object, the behaviour of fcntl() is the same as for a regular file except the effect of the following values for the argument cmd are unspecified: F_SETFL, F_GETLK, F_SETLK, and F_SETLKW.

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, will 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 will attempt to unlock only the requested segment.

 RETURN VALUE

Upon successful completion, the value returned depends on cmd as follows:

F_DUPFD

A new file descriptor.

F_GETFD

Value of flags defined in <fcntl.h>. The return value will not be negative.

F_SETFD

Value other than -1.

F_GETFL

Value of file status flags and access modes. The return value will not be 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.

Otherwise, -1 is returned and errno is set to indicate the error.

 ERRORS

The fcntl() function will 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 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 and {OPEN_MAX} file descriptors are currently open in the calling process, 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 some lock from another process and putting the calling process to sleep, waiting for that lock to become free would cause a deadlock.

 EXAMPLES

None.

 APPLICATION USAGE

None.

 FUTURE DIRECTIONS

None.

 SEE ALSO

close(), exec, open(), sigaction(), <fcntl.h>, <signal.h>, <sys/types.h>, <unistd.h>.

DERIVATION

Derived from Issue 1 of the SVID.