Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

fcntl(2) [bsd man page]

FCNTL(2)							System Calls Manual							  FCNTL(2)

NAME
fcntl - file control SYNOPSIS
#include <fcntl.h> res = fcntl(fd, cmd, arg) int res; int fd, cmd, arg; DESCRIPTION
Fcntl provides for control over descriptors. The argument fd is a descriptor to be operated on by cmd as follows: F_DUPFD Return a new descriptor as follows: Lowest numbered available descriptor greater than or equal to arg. Same object references as the original descriptor. New descriptor shares the same file pointer if the object was a file. 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 execv(2) system calls. F_GETFD Get the close-on-exec flag associated with the file descriptor fd. If the low-order bit is 0, the file will remain open across exec, otherwise the file will be closed upon execution of exec. F_SETFD Set the close-on-exec flag associated with fd to the low order bit of arg (0 or 1 as above). F_GETFL Get descriptor status flags, as described below. F_SETFL Set descriptor status flags. 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 group to receive SIGIO and SIGURG signals; process groups are specified by supplying arg as nega- tive, otherwise arg is interpreted as a process ID. The flags for the F_GETFL and F_SETFL flags are as follows: O_NONBLOCK Non-blocking I/O; if no data is available to a read call, or if a write operation would block, the call returns -1 with the error EWOULDBLOCK. O_APPEND Force each write to append at the end of file; corresponds to the O_APPEND flag of open(2). O_ASYNC Enable the SIGIO signal to be sent to the process group when I/O is possible, e.g., upon availability of data to be read. 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_GETFL Value of flags. F_GETOWN Value of file descriptor owner. other Value other than -1. Otherwise, a value of -1 is returned and errno is set to indicate the error. ERRORS
Fcntl will fail if one or more of the following are true: [EBADF] Fildes is not a valid open file descriptor. [EMFILE] Cmd is F_DUPFD and the maximum allowed number of file descriptors are currently open. [EINVAL] Cmd is F_DUPFD and arg is negative or greater than the maximum allowable number (see getdtablesize(2)). [ESRCH] Cmd is F_SETOWN and the process ID given as argument is not in use. SEE ALSO
close(2), execve(2), getdtablesize(2), open(2), sigvec(2) BUGS
The asynchronous I/O facilities of O_NONBLOCK and O_ASYNC are currently available only for tty and socket operations. 4.2 Berkeley Distribution Nov 30, 1994 FCNTL(2)

Check Out this Related Man Page

FCNTL(2)							System Calls Manual							  FCNTL(2)

NAME
fcntl - miscellaneous file descriptor control functions SYNOPSIS
#include <fcntl.h> int fcntl(int fd, int *cmd, [data]) DESCRIPTION
Fcntl() performs several file descriptor related functions, like duplicating a file descriptor, setting the "close on exec" attribute, etc. The fd argument is the file descriptor to operate on, cmd is the command code of the operation to perform, and data is an optional argument to give or receive parameters. The command codes and other symbols and types are declared in <fcntl.h>. The commands are: fcntl(fd, F_DUPFD, int fd2) Returns a new file descriptor that is a duplicate of file descriptor fd. It shares the same file pointer and the same file status flags, but has separate file descriptor flags that are initially off. The value of the duplicate file descriptor is the first free file descriptor greater than or equal to fd2. fcntl(fd, F_GETFD) Returns the file descriptor flags associated with file descriptor fd. The flags are the "close on exec" flag FD_CLOEXEC that, when set, causes the file descriptor to be closed when the process executes another program. The Minix-vmd specific FD_ASYNCHIO flag marks a file descriptor for asynchronous I/O operation. fcntl(fd, F_SETFD, int flags) Set the file descriptor flags of fd to flags. fcntl(fd, F_GETFL) Return the file status flags and file access modes associated with the file associated with file descriptor fd. The file status flags are O_NONBLOCK (non blocking I/O) and O_APPEND (append mode). The file access modes are O_RDONLY (read-only), O_WRONLY (write-only) and O_RDWR (read-write). These flags are also used in the second argument of open(2). fcntl(fd, F_SETFL, int flags) Set the file status flags of the file referenced by fd to flags. Only O_NONBLOCK and O_APPEND may be changed. Access mode flags are ignored. The next four commands use a parameter of type struct flock that is defined in <fcntl.h> as: struct flock { short l_type; /* F_RDLCK, F_WRLCK, or F_UNLCK */ short l_whence; /* SEEK_SET, SEEK_CUR, or SEEK_END */ off_t l_start; /* byte offset to start of segment */ off_t l_len; /* length of segment */ pid_t l_pid; /* process id of the locks' owner */ }; This structure describes a segment of a file. L_type is the lock operation performed on the file segment: F_RDLCK to set a read lock, F_WRLCK to set a write lock, and F_UNLCK to remove a lock. Several processes may have a read lock on a segment, but only one process can have a write lock. L_whence tells if the l_start offset must be interpreted from the start of the file (SEEK_SET), the current file posi- tion (SEEK_CUR), or the end of the file (SEEK_END). This is analogous to the third parameter of lseek(2). These SEEK_* symbols are declared in <unistd.h>. L_start is the starting offset of the segment of the file. L_end is the length of the segment. If zero then the segment extends until end of file. L_pid is the process-id of the process currently holding a lock on the segment. It is returned by F_GETLK. fcntl(fd, F_GETLK, struct flock *lkp) Find out if some other process has a lock on a segment of the file associated by file descriptor fd that overlaps with the segment described by the flock structure pointed to by lkp. If the segment is not locked then l_type is set to F_UNLCK. Otherwise an flock structure is returned through lkp that describes the lock held by the other process. L_start is set relative to the start of the file. fcntl(fd, F_SETLK, struct flock *lkp) Register a lock on a segment of the file associated with file descriptor fd. The file segment is described by the struct flock pointed to by lkp. This call returns an error if any part of the segment is already locked. fcntl(fd, F_SETLKW, struct flock *lkp) Register a lock on a segment of the file associated with file descriptor fd. The file segment is described by the struct flock pointed to by lkp. This call blocks waiting for the lock to be released if any part of the segment is already locked. fcntl(fd, F_FREESP, struct flock *lkp) Free a segment of disk space occupied by the file associated with file descriptor fd. The segment is described by the struct flock pointed to by lkp. The file is truncated in length to the byte position indicated by l_start if l_len is zero. If l_len is nonzero then the file keeps its size, but the freed bytes now read as zeros. (Other than sharing the flock structure, this call has nothing to do with locking.) fcntl(fd, F_SEEK, u64_t pos) This Minix-vmd specific call sets the file position of the file associated with file descriptor fd to the byte offset indicated by the 64-bit number pos. This is analogous to the call lseek(fd, pos, SEEK_SET) except that F_SEEK can be used on devices larger than 4 gigabyte. SEE ALSO
open(2), dup(2), lseek(2), ftruncate(3), int64(3). DIAGNOSTICS
Fcntl returns a file descriptor, flags, or 0 to indicate success. On error -1 is returned, with errno set to the appropriate error code. The most notable errors are: EINTR If a blocked F_SETLKW operation is interrupted by a signal that is caught. EAGAIN By F_SETLK if a segment cannot be locked. EBADF A bad file descriptor in general, or an attempt to place a write lock on a file that is not open for writing, etc. ENOLCK No locks available, the file system code has run out of internal table space. AUTHOR
Kees J. Bot (kjb@cs.vu.nl) FCNTL(2)
Man Page