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 descrip-
tor 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 descrip-
tor 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
position (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 over-
laps 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)
This Minix-vmd specific call frees 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.) (This call is common
among UNIX(-like) systems.)
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 writ-
ing, etc.
ENOLCK
No locks available, the file system code has run out of
internal table space.
AUTHOR
Kees J. Bot <kjb@cs.vu.nl>