174 lines
9.3 KiB
HTML
174 lines
9.3 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>fcntl(2)</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<H1>fcntl(2)</H1>
|
|
<HR>
|
|
<PRE>
|
|
|
|
</PRE>
|
|
<H2>NAME</H2><PRE>
|
|
fcntl - miscellaneous file descriptor control functions
|
|
|
|
|
|
</PRE>
|
|
<H2>SYNOPSIS</H2><PRE>
|
|
<STRONG>#include</STRONG> <STRONG><fcntl.h></STRONG>
|
|
|
|
<STRONG>int</STRONG> <STRONG>fcntl(int</STRONG> <EM>fd</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>cmd</EM><STRONG>,</STRONG> [<EM>data</EM>]<STRONG>)</STRONG>
|
|
|
|
|
|
</PRE>
|
|
<H2>DESCRIPTION</H2><PRE>
|
|
<STRONG>Fcntl()</STRONG> performs several file descriptor related functions, like
|
|
duplicating a file descriptor, setting the "close on exec" attribute,
|
|
etc. The <EM>fd</EM> argument is the file descriptor to operate on, <EM>cmd</EM> is the
|
|
command code of the operation to perform, and <EM>data</EM> 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:
|
|
|
|
<STRONG>fcntl(</STRONG><EM>fd</EM><STRONG>,</STRONG> <STRONG>F_DUPFD,</STRONG> <STRONG>int</STRONG> <EM>fd2</EM><STRONG>)</STRONG>
|
|
Returns a new file descriptor that is a duplicate of file descriptor
|
|
<EM>fd</EM>. 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 <EM>fd2</EM>.
|
|
|
|
<STRONG>fcntl(</STRONG><EM>fd</EM><STRONG>,</STRONG> <STRONG>F_GETFD)</STRONG>
|
|
Returns the file descriptor flags associated with file descriptor
|
|
<EM>fd</EM>. The flags are the "close on exec" flag <STRONG>FD_CLOEXEC</STRONG> that, when
|
|
set, causes the file descriptor to be closed when the process
|
|
executes another program. The Minix-vmd specific <STRONG>FD_ASYNCHIO</STRONG> flag
|
|
marks a file descriptor for asynchronous I/O operation.
|
|
|
|
<STRONG>fcntl(</STRONG><EM>fd</EM><STRONG>,</STRONG> <STRONG>F_SETFD,</STRONG> <STRONG>int</STRONG> <EM>flags</EM><STRONG>)</STRONG>
|
|
Set the file descriptor flags of <EM>fd</EM> to <EM>flags</EM>.
|
|
|
|
<STRONG>fcntl(</STRONG><EM>fd</EM><STRONG>,</STRONG> <STRONG>F_GETFL)</STRONG>
|
|
Return the file status flags and file access modes associated with
|
|
the file associated with file descriptor <EM>fd</EM>. The file status flags
|
|
are <STRONG>O_NONBLOCK</STRONG> (non blocking I/O) and <STRONG>O_APPEND</STRONG> (append mode). The
|
|
file access modes are <STRONG>O_RDONLY</STRONG> (read-only), <STRONG>O_WRONLY</STRONG> (write-only)
|
|
and <STRONG>O_RDWR</STRONG> (read-write). These flags are also used in the second
|
|
argument of <STRONG><A HREF="../man2/open.2.html">open(2)</A></STRONG>.
|
|
|
|
<STRONG>fcntl(</STRONG><EM>fd</EM><STRONG>,</STRONG> <STRONG>F_SETFL,</STRONG> <STRONG>int</STRONG> <EM>flags</EM><STRONG>)</STRONG>
|
|
Set the file status flags of the file referenced by <EM>fd</EM> to <EM>flags</EM>.
|
|
Only <STRONG>O_NONBLOCK</STRONG> and <STRONG>O_APPEND</STRONG> may be changed. Access mode flags are
|
|
ignored.
|
|
|
|
The next four commands use a parameter of type <STRONG>struct</STRONG> <STRONG>flock</STRONG> 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. <STRONG>L_type</STRONG> is the lock
|
|
operation performed on the file segment: <STRONG>F_RDLCK</STRONG> to set a read lock,
|
|
<STRONG>F_WRLCK</STRONG> to set a write lock, and <STRONG>F_UNLCK</STRONG> to remove a lock. Several
|
|
processes may have a read lock on a segment, but only one process can
|
|
have a write lock. <STRONG>L_whence</STRONG> tells if the <STRONG>l_start</STRONG> offset must be
|
|
interpreted from the start of the file (<STRONG>SEEK_SET</STRONG>), the current file
|
|
position (<STRONG>SEEK_CUR</STRONG>), or the end of the file (<STRONG>SEEK_END</STRONG>). This is
|
|
analogous to the third parameter of <STRONG><A HREF="../man2/lseek.2.html">lseek(2)</A></STRONG>. These <STRONG>SEEK_*</STRONG> symbols are
|
|
declared in <unistd.h>. <STRONG>L_start</STRONG> is the starting offset of the segment of
|
|
the file. <STRONG>L_end</STRONG> is the length of the segment. If zero then the segment
|
|
extends until end of file. <STRONG>L_pid</STRONG> is the process-id of the process
|
|
currently holding a lock on the segment. It is returned by <STRONG>F_GETLK</STRONG>.
|
|
|
|
<STRONG>fcntl(</STRONG><EM>fd</EM><STRONG>,</STRONG> <STRONG>F_GETLK,</STRONG> <STRONG>struct</STRONG> <STRONG>flock</STRONG> <STRONG>*</STRONG><EM>lkp</EM><STRONG>)</STRONG>
|
|
Find out if some other process has a lock on a segment of the file
|
|
associated by file descriptor <EM>fd</EM> that overlaps with the segment
|
|
described by the <STRONG>flock</STRONG> structure pointed to by <EM>lkp</EM>. If the segment
|
|
is not locked then <STRONG>l_type</STRONG> is set to <STRONG>F_UNLCK</STRONG>. Otherwise an <STRONG>flock</STRONG>
|
|
structure is returned through <EM>lkp</EM> that describes the lock held by
|
|
the other process. <STRONG>L_start</STRONG> is set relative to the start of the
|
|
file.
|
|
|
|
<STRONG>fcntl(</STRONG><EM>fd</EM><STRONG>,</STRONG> <STRONG>F_SETLK,</STRONG> <STRONG>struct</STRONG> <STRONG>flock</STRONG> <STRONG>*</STRONG><EM>lkp</EM><STRONG>)</STRONG>
|
|
Register a lock on a segment of the file associated with file
|
|
descriptor <EM>fd</EM>. The file segment is described by the <STRONG>struct</STRONG> <STRONG>flock</STRONG>
|
|
pointed to by <EM>lkp</EM>. This call returns an error if any part of the
|
|
segment is already locked.
|
|
|
|
<STRONG>fcntl(</STRONG><EM>fd</EM><STRONG>,</STRONG> <STRONG>F_SETLKW,</STRONG> <STRONG>struct</STRONG> <STRONG>flock</STRONG> <STRONG>*</STRONG><EM>lkp</EM><STRONG>)</STRONG>
|
|
Register a lock on a segment of the file associated with file
|
|
descriptor <EM>fd</EM>. The file segment is described by the <STRONG>struct</STRONG> <STRONG>flock</STRONG>
|
|
pointed to by <EM>lkp</EM>. This call blocks waiting for the lock to be
|
|
released if any part of the segment is already locked.
|
|
|
|
<STRONG>fcntl(</STRONG><EM>fd</EM><STRONG>,</STRONG> <STRONG>F_FREESP,</STRONG> <STRONG>struct</STRONG> <STRONG>flock</STRONG> <STRONG>*</STRONG><EM>lkp</EM><STRONG>)</STRONG>
|
|
Free a segment of disk space occupied by the file associated with
|
|
file descriptor <EM>fd</EM>. The segment is described by the <STRONG>struct</STRONG> <STRONG>flock</STRONG>
|
|
pointed to by <EM>lkp</EM>. The file is truncated in length to the byte
|
|
position indicated by <STRONG>l_start</STRONG> if <STRONG>l_len</STRONG> is zero. If <STRONG>l_len</STRONG> 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.)
|
|
|
|
<STRONG>fcntl(</STRONG><EM>fd</EM><STRONG>,</STRONG> <STRONG>F_SEEK,</STRONG> <STRONG>u64_t</STRONG> <EM>pos</EM><STRONG>)</STRONG>
|
|
This Minix-vmd specific call sets the file position of the file
|
|
associated with file descriptor <EM>fd</EM> to the byte offset indicated by
|
|
the 64-bit number <EM>pos</EM>. This is analogous to the call
|
|
|
|
<STRONG>lseek(</STRONG><EM>fd</EM><STRONG>,</STRONG> <EM>pos</EM><STRONG>,</STRONG> <STRONG>SEEK_SET)</STRONG>
|
|
|
|
except that <STRONG>F_SEEK</STRONG> can be used on devices larger than 4 gigabyte.
|
|
|
|
|
|
</PRE>
|
|
<H2>SEE ALSO</H2><PRE>
|
|
<STRONG><A HREF="../man2/open.2.html">open(2)</A></STRONG>, <STRONG><A HREF="../man2/dup.2.html">dup(2)</A></STRONG>, <STRONG><A HREF="../man2/lseek.2.html">lseek(2)</A></STRONG>, <STRONG><A HREF="../man3/ftruncate.3.html">ftruncate(3)</A></STRONG>, <STRONG><A HREF="../man3/int64.3.html">int64(3)</A></STRONG>.
|
|
|
|
|
|
</PRE>
|
|
<H2>DIAGNOSTICS</H2><PRE>
|
|
<STRONG>Fcntl</STRONG> returns a file descriptor, flags, or <STRONG>0</STRONG> to indicate success. On
|
|
error <STRONG>-1</STRONG> is returned, with <STRONG>errno</STRONG> set to the appropriate error code. The
|
|
most notable errors are:
|
|
|
|
<STRONG>EINTR</STRONG>
|
|
If a blocked <STRONG>F_SETLKW</STRONG> operation is interrupted by a signal that is
|
|
caught.
|
|
|
|
<STRONG>EAGAIN</STRONG>
|
|
By <STRONG>F_SETLK</STRONG> if a segment cannot be locked.
|
|
|
|
<STRONG>EBADF</STRONG>
|
|
A bad file descriptor in general, or an attempt to place a write
|
|
lock on a file that is not open for writing, etc.
|
|
|
|
<STRONG>ENOLCK</STRONG>
|
|
No locks available, the file system code has run out of internal
|
|
table space.
|
|
|
|
|
|
</PRE>
|
|
<H2>AUTHOR</H2><PRE>
|
|
Kees J. Bot (kjb@cs.vu.nl)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</PRE>
|
|
</BODY>
|
|
</HTML>
|