NAME

fcntl − file control

SYNOPSIS

#include <fcntl.h>

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

DESCRIPTION

fcntl provides for control over open files.  fildes is an open file descriptor obtained from a creat, open, dup, fcntl, or pipe system call. 

The commands available are:

F_DUPFD Return a new file descriptor as follows:

Lowest numbered available file descriptor greater than or equal to arg.

Same open file (or pipe) as the original file. 

Same file pointer as the original file (i.e., both file descriptors share one file pointer). 

Same access mode (read, write or read/write). 

Same file status flags (i.e., both file descriptors share the same file status flags). 

The close-on-exec flag associated with the new file descriptor is set to remain open across exec(2) system calls.

F_GETFD Get the close-on-exec flag associated with the file descriptor fildes. If the low-order bit is 0 the file remains open across exec; otherwise the file is closed upon execution of exec.

F_SETFD Set the close-on-exec flag associated with fildes to the low-order bit of arg (0 or 1 as above). 

F_GETFL Get file status flags. 

F_SETFL Set file status flags to arg. Only certain flags can be set [see fcntl(5)].

F_GETLK Get the first lock which blocks the lock description given by the variable of type struct flock pointed to by arg.  The information retrieved overwrites the information passed to fcntl in the flock structure.  If no lock is found that would prevent this lock from being created, then the structure is passed back unchanged except for the lock type which is set to F_UNLCK. 

F_SETLK Set or clear a file segment lock according to the variable of type struct flock pointed to by arg [see fcntl(5)].  The cmd F_SETLK is used to establish read (F_RDLCK) and write (F_WRLCK) locks, as well as remove either type of lock (F_UNLCK).  If a read or write lock cannot be set, fcntl returns immediately with an error value of −1. 

F_SETLKW This cmd is the same as F_SETLK except that if a read or write lock is blocked by other locks, the process sleeps until the segment is free to be locked. 

F_GETOWN Get the process ID or process group currently receiving SIGIO and SIGURG signals; process groups are returned as negative values. 

F_SETOWN Set the process or process groups to receive SIGIO and SIGURG signals; process groups are specified by supplying arg as negative, otherwise arg is interpreted as a process ID. 

F_GETOWN and F_SETOWN apply only to STREAMS devices, not regular files or pipes. 

A read lock prevents any process from write locking the protected area.  More than one read lock may exist for a given segment of a file at a given time.  The file descriptor on which a read lock is being placed must have been opened with read access. 

A write lock prevents any process from read locking or write locking the protected area.  Only one write lock may exist for a given segment of a file at a given time.  The file descriptor on which a write lock is being placed must have been opened with write access. 

The structure flock describes the type (l_type), starting offset (l_whence), relative offset (l_start), size (l_len), process id (l_pid), and RFS system id (l_sysid) of the segment of the file to be affected.  The process id and system id fields are used only with the F_GETLK cmd to return the values for a blocking lock.  Locks may start and extend beyond the current end of a file, but may not be negative relative to the beginning of the file.  A lock may be set always to extend to the end of file by setting l_len to zero (0).  If such a lock also has l_whence and l_start set to zero (0), the whole file is locked.  Changing or unlocking a segment from the middle of a larger locked segment leaves two smaller segments for either end.  Locking a segment that is already locked by the calling process causes the old lock type to be removed and the new lock type to take effect.  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 in a fork(2) system call. 

When mandatory file and record locking is active on a file, [see chmod(2)], read and write system calls issued on the file are affected by the record locks in effect. 

fcntl fails if one or more of the following are true:

­[EBADF] fildes is not a valid open file descriptor. 

­[EINVAL] cmd is F_DUPFD.  arg is either negative, or greater than or equal to the configured value for the maximum number of open file descriptors allowed each user. 

[EINVAL] cmd is F_GETLK, F_SETLK, or SETLKW and arg or the data it points to is not valid. 

[EACCES] cmd is F_SETLK the type of lock (l_type) is a read (F_RDLCK) lock and the segment of a file to be locked is already write locked by another process or the type is a write (F_WRLCK) lock and the segment of a file to be locked is already read or write locked by another process. 

[ENOLCK] cmd is F_SETLK or F_SETLKW, the type of lock is a read or write lock, and there are no more record locks available (too many file segments locked) because the system maximum has been exceeded. 

[EDEADLK] cmd 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. 

[EFAULT] cmd is F_SETLK, arg points outside the program address space. 

[EINTR] A signal was caught during the fcntl system call. 

[ENOLINK] fildes is on a remote machine and the link to that machine is no longer active. 

SEE ALSO

close(2), creat(2), dup(2), exec(2), fork(2), open(2), pipe(2), signal(2), fcntl(5). 

DIAGNOSTICS

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

F_DUPFD A new file descriptor. 

F_GETFD Value of flag (only the low-order bit is defined). 

F_SETFD Value other than −1. 

F_GETFL Value of file flags. 

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 Process or process group ID of the file owner. 

Otherwise, a value of −1 is returned and errno is set to indicate the error. 

WARNINGS

Because in the future the variable errno will be set to EAGAIN rather than EACCES when a section of a file is already locked by another process, portable application programs should expect and test for either value. 

September 02, 1992