<H2><A NAME="SEC183" HREF="library_toc.html#SEC183" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC183">File Descriptor Flags</A></H2>
<P>
<DFN>File descriptor flags</DFN> are miscellaneous attributes of a file
descriptor.  These flags are associated with particular file
descriptors, so that if you have created duplicate file descriptors
from a single opening of a file, each descriptor has its own set of flags.
<P>
Currently there is just one file descriptor flag: <CODE>FD_CLOEXEC</CODE>,
which causes the descriptor to be closed if you use any of the
<CODE>exec...</CODE> functions (see section <A HREF="library_23.html#SEC406" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html#SEC406">Executing a File</A>).
<P>
The symbols in this section are defined in the header file
<TT>`fcntl.h'</TT>.
<A NAME="IDX696"></A>
<P>
<A NAME="IDX697"></A>
<U>Macro:</U> int <B>F_GETFD</B><P>
This macro is used as the <VAR>command</VAR> argument to <CODE>fcntl</CODE>, to
specify that it should return the file descriptor flags associated
with the <VAR>filedes</VAR> argument.  
<P>
The normal return value from <CODE>fcntl</CODE> with this command is a
nonnegative number which can be interpreted as the bitwise OR of the
individual flags (except that currently there is only one flag to use).
<P>
In case of an error, <CODE>fcntl</CODE> returns <CODE>-1</CODE>.  The following
<CODE>errno</CODE> error conditions are defined for this command:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is invalid.
</DL>
<P>
<A NAME="IDX698"></A>
<U>Macro:</U> int <B>F_SETFD</B><P>
This macro is used as the <VAR>command</VAR> argument to <CODE>fcntl</CODE>, to
specify that it should set the file descriptor flags associated with the
<VAR>filedes</VAR> argument.  This requires a third <CODE>int</CODE> argument to
specify the new flags, so the form of the call is:
<P>
<PRE>
fcntl (<VAR>filedes</VAR>, F_SETFD, <VAR>new_flags</VAR>)
</PRE>
<P>
The normal return value from <CODE>fcntl</CODE> with this command is an
unspecified value other than <CODE>-1</CODE>, which indicates an error.
The flags and error conditions are the same as for the <CODE>F_GETFD</CODE>
command.
<P>
The following macro is defined for use as a file descriptor flag with
the <CODE>fcntl</CODE> function.  The value is an integer constant usable
as a bit mask value.
<P>
<A NAME="IDX699"></A>
<A NAME="IDX700"></A>
<U>Macro:</U> int <B>FD_CLOEXEC</B><P>
This flag specifies that the file descriptor should be closed when
an <CODE>exec</CODE> function is invoked; see section <A HREF="library_23.html#SEC406" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html#SEC406">Executing a File</A>.  When
a file descriptor is allocated (as with <CODE>open</CODE> or <CODE>dup</CODE>),
this bit is initially cleared on the new file descriptor, meaning that
descriptor will survive into the new program after <CODE>exec</CODE>.
<P>
If you want to modify the file descriptor flags, you should get the
current flags with <CODE>F_GETFD</CODE> and modify the value.  Don't assume
that the flag listed here is the only ones that are implemented; your
program may be run years from now and more flags may exist then.
For example, here is a function to set or clear the flag <CODE>FD_CLOEXEC</CODE>
without altering any other flags:
<P>
<PRE>
/* Set the <CODE>FD_CLOEXEC</CODE> flag of <VAR>desc</VAR> if <VAR>value</VAR> is nonzero,
   or clear the flag if <VAR>value</VAR> is 0.
   Return 0 on success, or -1 on error with <CODE>errno</CODE> set. */ 

int
set_cloexec_flag (int desc, int value)
{
  int oldflags = fcntl (desc, F_GETFD, 0);
  /* If reading the flags failed, return error indication now.
  if (oldflags &#60; 0)
    return oldflags;
  /* Set just the flag we want to set. */
  if (value != 0)
    oldflags |= FD_CLOEXEC;
  else
    oldflags &#38;= ~FD_CLOEXEC;
  /* Store modified flag word in the descriptor. */
  return fcntl (desc, F_SETFD, oldflags);
}
</PRE>
<P>
<A NAME="IDX701"></A>
<H2><A NAME="SEC184" HREF="library_toc.html#SEC184" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC184">File Status Flags</A></H2>
<P>
<DFN>File status flags</DFN> are used to specify attributes of the opening of
a file.  Unlike the file descriptor flags discussed in section <A HREF="library_12.html#SEC183" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC183">File Descriptor Flags</A>, the file status flags are shared by duplicated file descriptors
resulting from a single opening of the file.
<P>
The file status flags are initialized by the <CODE>open</CODE> function from
the <VAR>flags</VAR> argument of the <CODE>open</CODE> function.  Some of the flags
are meaningful only in <CODE>open</CODE> and are not remembered subsequently;
many of the rest cannot subsequently be changed, though you can read
their values by examining the file status flags.
<P>
A few file status flags can be changed at any time using <CODE>fcntl</CODE>.
These include <CODE>O_APPEND</CODE> and <CODE>O_NONBLOCK</CODE>.
<P>
The symbols in this section are defined in the header file
<TT>`fcntl.h'</TT>.
<A NAME="IDX702"></A>
<P>
<A NAME="IDX703"></A>
<U>Macro:</U> int <B>F_GETFL</B><P>
This macro is used as the <VAR>command</VAR> argument to <CODE>fcntl</CODE>, to
read the file status flags for the open file with descriptor
<VAR>filedes</VAR>.
<P>
The normal return value from <CODE>fcntl</CODE> with this command is a
nonnegative number which can be interpreted as the bitwise OR of the
individual flags.  The flags are encoded like the <VAR>flags</VAR> argument
to <CODE>open</CODE> (see section <A HREF="library_12.html#SEC172" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC172">Opening and Closing Files</A>), but only the file
access modes and the <CODE>O_APPEND</CODE> and <CODE>O_NONBLOCK</CODE> flags are
meaningful here.  Since the file access modes are not single-bit values,
you can mask off other bits in the returned flags with <CODE>O_ACCMODE</CODE>
to compare them.
<P>
In case of an error, <CODE>fcntl</CODE> returns <CODE>-1</CODE>.  The following
<CODE>errno</CODE> error conditions are defined for this command:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is invalid.
</DL>
<P>
<A NAME="IDX704"></A>
<U>Macro:</U> int <B>F_SETFL</B><P>
This macro is used as the <VAR>command</VAR> argument to <CODE>fcntl</CODE>, to set
the file status flags for the open file corresponding to the
<VAR>filedes</VAR> argument.  This command requires a third <CODE>int</CODE>
argument to specify the new flags, so the call looks like this:
<P>
<PRE>
fcntl (<VAR>filedes</VAR>, F_SETFL, <VAR>new_flags</VAR>)
</PRE>
<P>
You can't change the access mode for the file in this way; that is,
whether the file descriptor was opened for reading or writing.  You can
only change the <CODE>O_APPEND</CODE> and <CODE>O_NONBLOCK</CODE> flags.
<P>
The normal return value from <CODE>fcntl</CODE> with this command is an
unspecified value other than <CODE>-1</CODE>, which indicates an error.  The
error conditions are the same as for the <CODE>F_GETFL</CODE> command.
<P>
The following macros are defined for use in analyzing and constructing
file status flag values:
<P>
<DL COMPACT>
<DT><CODE>O_APPEND</CODE>
<DD>The bit that enables append mode for the file.  If set, then all
<CODE>write</CODE> operations write the data at the end of the file, extending
it, regardless of the current file position.
<P>
<DT><CODE>O_NONBLOCK</CODE>
<DD>The bit that enables nonblocking mode for the file.  If this bit is set,
<CODE>read</CODE> requests on the file can return immediately with a failure
status if there is no input immediately available, instead of blocking.
Likewise, <CODE>write</CODE> requests can also return immediately with a
failure status if the output can't be written immediately.
<P>
<DT><CODE>O_NDELAY</CODE>
<DD>This is a synonym for <CODE>O_NONBLOCK</CODE>, provided for compatibility with
BSD.
</DL>
<P>
<A NAME="IDX705"></A>
<U>Macro:</U> int <B>O_ACCMODE</B><P>
This macro stands for a mask that can be bitwise-ANDed with the file
status flag value to produce a value representing the file access mode.
The mode will be <CODE>O_RDONLY</CODE>, <CODE>O_WRONLY</CODE>, or <CODE>O_RDWR</CODE>.
<P>
<DL COMPACT>
<DT><CODE>O_RDONLY</CODE>
<DD>Open the file for read access.
<P>
<DT><CODE>O_WRONLY</CODE>
<DD>Open the file for write access.
<P>
<DT><CODE>O_RDWR</CODE>
<DD>Open the file for both reading and writing.
</DL>
<P>
If you want to modify the file status flags, you should get the current
flags with <CODE>F_GETFL</CODE> and modify the value.  Don't assume that the
flags listed here are the only ones that are implemented; your program
may be run years from now and more flags may exist then.  For example,
here is a function to set or clear the flag <CODE>O_NONBLOCK</CODE> without
altering any other flags:
<P>
<PRE>
/* Set the <CODE>O_NONBLOCK</CODE> flag of <VAR>desc</VAR> if <VAR>value</VAR> is nonzero,
   or clear the flag if <VAR>value</VAR> is 0.
   Return 0 on success, or -1 on error with <CODE>errno</CODE> set. */ 

int
set_nonblock_flag (int desc, int value)
{
  int oldflags = fcntl (desc, F_GETFL, 0);
  /* If reading the flags failed, return error indication now. */
  if (oldflags &#60; 0)
    return oldflags;
  /* Set just the flag we want to set. */
  if (value != 0)
    oldflags |= O_NONBLOCK;
  else
    oldflags &#38;= ~O_NONBLOCK;
  /* Store modified flag word in the descriptor. */
  return fcntl (desc, F_SETFL, oldflags);
}
</PRE>
<P>
<H2><A NAME="SEC185" HREF="library_toc.html#SEC185" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC185">File Locks</A></H2>
<A NAME="IDX706"></A>
<A NAME="IDX707"></A>
<P>
The remaining <CODE>fcntl</CODE> commands are used to support <DFN>record
locking</DFN>, which permits multiple cooperating programs to prevent each
other from simultaneously accessing parts of a file in error-prone
ways.
<A NAME="IDX708"></A>
<A NAME="IDX709"></A>
<P>
An <DFN>exclusive</DFN> or <DFN>write</DFN> lock gives a process exclusive access
for writing to the specified part of the file.  While a write lock is in
place, no other process can lock that part of the file.
<A NAME="IDX710"></A>
<A NAME="IDX711"></A>
<P>
A <DFN>shared</DFN> or <DFN>read</DFN> lock prohibits any other process from
requesting a write lock on the specified part of the file.  However,
other processes can request read locks.
<P>
The <CODE>read</CODE> and <CODE>write</CODE> functions do not actually check to see
whether there are any locks in place.  If you want to implement a
locking protocol for a file shared by multiple processes, your application
must do explicit <CODE>fcntl</CODE> calls to request and clear locks at the
appropriate points.
<P>
Locks are associated with processes.  A process can only have one kind
of lock set for each byte of a given file.  When any file descriptor for
that file is closed by the process, all of the locks that process holds
on that file are released, even if the locks were made using other
descriptors that remain open.  Likewise, locks are released when a
process exits, and are not inherited by child processes created using
<CODE>fork</CODE> (see section <A HREF="library_23.html#SEC405" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html#SEC405">Creating a Process</A>).
<P>
When making a lock, use a <CODE>struct flock</CODE> to specify what kind of
lock and where.  This data type and the associated macros for the
<CODE>fcntl</CODE> function are declared in the header file <TT>`fcntl.h'</TT>.
<A NAME="IDX712"></A>
<P>
<A NAME="IDX713"></A>
<U>struct Type:</U> <B>flock</B><P>
This structure is used with the <CODE>fcntl</CODE> function to describe a file
lock.  It has these members:
<P>
<DL COMPACT>
<DT><CODE>short int l_type</CODE>
<DD>Specifies the type of the lock;