NAME

fcntl − file control

SYNOPSIS

#include <sys/types.h>
#include <unistd.h>
#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 data type and value of arg are specific to the type of command specified by cmd. The symbolic names for commands and file status flags are defined by the <fcntl.h> header file. 

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 flag is set to FD_CLOEXEC the file will be closed upon execution of exec(2), otherwise the file will remain open across exec(2). 

F_SETFD Set the close-on-exec flag associated with fildes with the value in arg which must be either a 0 or FD_CLOEXEC. 

F_GETFL Get file status flags: O_RDONLY, O_WRONLY, O_RDWR, O_NDELAY, O_NONBLOCK, O_APPEND, O_SYNC, O_DIRECT. 

F_SETFL Set file status flags to arg. Only the flags O_NDELAY, O_NONBLOCK, O_APPEND, O_DSYNC and O_SYNC may be set with fcntl. If the file descriptor fildes is a regular disk file descriptor, then direct I/O may be switched ON or OFF by providing the O_DIRECT or O_DIRECTOFF flag respectively. The O_DIRECT and O_DIRECTOFF flags may not be used together. 

F_CHKFL Check the value of arg for validity.  -1 is returned if arg is invalid.  A value greater than or equal to zero is returned if arg is valid. 

F_GETASYNC
Get the asynchronous I/O support information for the file descriptor fildes. If the low-order bit is 0 asynchronous I/O operations are not supported by the file descriptor, otherwise asynchronous I/O operations are supported by the file descriptor.  Note that for files which do not support asynchronous I/O operations, aread(2) and awrite(2) may be used (they will actually perform synchronous I/O operations, but the interface to the user will appear to be asynchronous). 

F_EXTSIZE Allocate space to the disk file associated with fildes on a Contiguous Best Try basis. That is, space will be allocated with as few separate contiguous extents as possible.  fcntl returns the number of such extents allocated.  Arg specifies the allocation size, in bytes.  The allocation size is rounded up to the file system block’s block size (see stat(2)).  The file’s size (see stat(2)), is updated to be the allocation size. 

In the att universe, the following commands are also available:

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 will be set to F_UNLCK. 

F_SETLK Set or clear an advisory or enforced 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 (shared) (F_RDLCK) and write (exclusive) (F_WRLCK) locks, as well as remove either type of lock (F_UNLCK).  If a read or write lock cannot be set, fcntl will return 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 will sleep until the segment is free to be locked. 

When a read-lock has been set on a segment of a file, other processes may also set read-locks on that segment or a portion of it. A read-lock prevents any other process from setting a write-lock on any portion of the protected area.  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 setting a read-lock or a write-lock on any portion of the protected area.  Only one write-lock and no read-locks 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), 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, will be measured in bytes from the start of the file, current position, or end of file, respectively. The value of l_len is the number of consecutive bytes to be locked.  The process id field, l_pid, is only used with the F_GETLK cmd to return the value 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 to always extend to the end of file by setting l_len to zero (0).  If such a lock also has l_start set to zero (0), the whole file will be locked. 

Changing or unlocking a segment from the middle of a larger locked segment leaves two smaller segments at each end of the originally locked segment.  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 affect.  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 after executing a fork(2) system call. 

Advisory locks allow cooperating processes to perform consistent operations on files, but do not guarantee exclusive access (i.e., processes may still access files without using advisory locks, possibly resulting in inconsistencies). 

If an ordinary files has enforced record locking enabled (see chmod(2)), record locks on the file will affect calls to open(2), creat(2), read(2), and write(2). 

F_FREESP
Free storage space associated with the file descriptor according to the variable of type struct flock pointed to by arg [see fcntl(5)].  The portion to be freed is specified by l_start, l_whence, and l_len.  The l_len field shall be zero. 

In the ucb universe, the following commands are also available:

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

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

fcntl will fail if one or more of the following are true:

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

­[ENODEV] Cmd is F_EXTSIZE and the file is managed by a client of a Network File System (NFS) server. 

­[ENOSPC] Cmd is F_EXTSIZE and there is insufficient space on the file system for the requested allocation. 

­[EINVAL] Cmd is F_SETFL and both O_DIRECT and O_DIRECTOFF flags are set. 

­[EINVAL] Cmd is F_SETFL and a flag other than one of the following flags has been passed in: O_NDELAY, O_APPEND, O_NONBLOCK, O_DSYNC, O_SYNC, O_DIRECT and O_DIRECTOFF. 

­[EINVAL] Cmd is F_EXTSIZE and the specified size is less than or equal to zero. 

­[EFBIG] Cmd is F_EXTSIZE and the specified size is too large. 

­[EMFILE] Cmd is F_DUPFD and the number of file descriptors currently open in the calling process is the maximum allowed to the process. 

­[EINVAL] Cmd is F_DUPFD and arg is negative or greater than or equal to the maximum number of open file descriptors allowed to the process (see getrlimit(2)). 

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

[EACCESS] Cmd is F_SETLK the type of lock (l_type) is a read (F_RDLCK) or write (F_WRLCK) lock and the segment of a file to be locked is already write locked by another process or the type is a write lock and the segment of a file to be locked is already read or write locked by another process.  [EACCES] cmd is F_SETLK or F_SETLKW and the security label of the user and file are not equal. 

[ENOLCK] Cmd is F_SETLK or F_SETLKW, the type of lock is a read or write lock and there are no more file locking headers available (too many files have segments locked) or there are no more record locks available (too many file segments locked). 

­[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. 

RETURN VALUE

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_CHKFL -1 if check fails.  Greater than or equal to zero if it succeeds. 

F_SETFL Value other than −1. 

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

F_GETLK Value other than −1. 

F_SETLK Value other than −1. 

F_SETLKW Value other than −1. 

F_FREESP Value other than −1. 

F_GETOWN Value of the file descriptor owner. 

F_SETOWN Value other than −1. 

F_EXTSIZE Number of separate contiguous extents needed to extend the file. 

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

SEE ALSO

aread(2), awrite(2), close(2), exec(2), open(2), fcntl(5), getrlimit(2). 

CX/UX Programmer’s Reference Manual