The return value from <CODE>fchown</CODE> is <CODE>0</CODE> on success and <CODE>-1</CODE>
on failure.  The following <CODE>errno</CODE> error codes are defined for this
function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>filedes</VAR> argument corresponds to a pipe or socket, not an ordinary
file.
<P>
<DT><CODE>EPERM</CODE>
<DD>This process lacks permission to make the requested change.  For
details, see <CODE>chmod</CODE>, above.
<P>
<DT><CODE>EROFS</CODE>
<DD>The file resides on a read-only file system.
</DL>
<P>
<H3><A NAME="SEC205" HREF="library_toc.html#SEC205" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC205">The Mode Bits for Access Permission</A></H3>
<P>
The <DFN>file mode</DFN>, stored in the <CODE>st_mode</CODE> field of the file
attributes, contains two kinds of information: the file type code, and
the access permission bits.  This section discusses only the access
permission bits, which control who can read or write the file.
See section <A HREF="library_13.html#SEC203" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC203">Testing the Type of a File</A>, for information about the file type code.
<P>
All of the symbols listed in this section are defined in the header file
<TT>`sys/stat.h'</TT>.
<A NAME="IDX817"></A>
<A NAME="IDX818"></A>
<P>
These symbolic constants are defined for the file mode bits that control
access permission for the file:
<P>
<DL COMPACT>
<A NAME="IDX819"></A>
<DT><CODE>S_IRUSR</CODE>
<DD><A NAME="IDX820"></A>
<DT><CODE>S_IREAD</CODE>
<DD>Read permission bit for the owner of the file.  On many systems, this
bit is 0400.  <CODE>S_IREAD</CODE> is an obsolete synonym provided for BSD
compatibility.
<P>
<A NAME="IDX821"></A>
<DT><CODE>S_IWUSR</CODE>
<DD><A NAME="IDX822"></A>
<DT><CODE>S_IWRITE</CODE>
<DD>Write permission bit for the owner of the file.  Usually 0200.
<CODE>S_IWRITE</CODE> is an obsolete synonym provided for BSD compatibility.
<P>
<A NAME="IDX823"></A>
<DT><CODE>S_IXUSR</CODE>
<DD><A NAME="IDX824"></A>
<DT><CODE>S_IEXEC</CODE>
<DD>Execute (for ordinary files) or search (for directories) permission bit
for the owner of the file.  Usually 0100.  <CODE>S_IEXEC</CODE> is an obsolete
synonym provided for BSD compatibility.
<P>
<A NAME="IDX825"></A>
<DT><CODE>S_IRWXU</CODE>
<DD>This is equivalent to <SAMP>`(S_IRUSR | S_IWUSR | S_IXUSR)'</SAMP>.
<P>
<A NAME="IDX826"></A>
<DT><CODE>S_IRGRP</CODE>
<DD>Read permission bit for the group owner of the file.  Usually 040.
<P>
<A NAME="IDX827"></A>
<DT><CODE>S_IWGRP</CODE>
<DD>Write permission bit for the group owner of the file.  Usually 020.
<P>
<A NAME="IDX828"></A>
<DT><CODE>S_IXGRP</CODE>
<DD>Execute or search permission bit for the group owner of the file.
Usually 010.
<P>
<A NAME="IDX829"></A>
<DT><CODE>S_IRWXG</CODE>
<DD>This is equivalent to <SAMP>`(S_IRGRP | S_IWGRP | S_IXGRP)'</SAMP>.
<P>
<A NAME="IDX830"></A>
<DT><CODE>S_IROTH</CODE>
<DD>Read permission bit for other users.  Usually 04.
<P>
<A NAME="IDX831"></A>
<DT><CODE>S_IWOTH</CODE>
<DD>Write permission bit for other users.  Usually 02.
<P>
<A NAME="IDX832"></A>
<DT><CODE>S_IXOTH</CODE>
<DD>Execute or search permission bit for other users.  Usually 01.
<P>
<A NAME="IDX833"></A>
<DT><CODE>S_IRWXO</CODE>
<DD>This is equivalent to <SAMP>`(S_IROTH | S_IWOTH | S_IXOTH)'</SAMP>.
<P>
<A NAME="IDX834"></A>
<DT><CODE>S_ISUID</CODE>
<DD>This is the set-user-ID on execute bit, usually 04000. 
See section <A HREF="library_25.html#SEC433" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_25.html#SEC433">How an Application Can Change Persona</A>.
<P>
<A NAME="IDX835"></A>
<DT><CODE>S_ISGID</CODE>
<DD>This is the set-group-ID on execute bit, usually 02000.
See section <A HREF="library_25.html#SEC433" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_25.html#SEC433">How an Application Can Change Persona</A>.
<A NAME="IDX836"></A>
<P>
<A NAME="IDX837"></A>
<DT><CODE>S_ISVTX</CODE>
<DD>This is the <DFN>sticky</DFN> bit, usually 01000.
<P>
On an executable file, it modifies the swapping policies of the system.
Normally, when a program terminates, its pages in core are immediately
freed and reused.  If the sticky bit is set on the executable file, the
system keeps the pages in core for a while as if the program were still
running.  This is advantageous for a program that is likely to be run
many times in succession.
<P>
On a directory, the sticky bit gives permission to delete a file in the
directory if you can write the contents of that file.  Ordinarily, a
user either can delete all the files in the directory or cannot delete
any of them (based on whether the user has write permission for the
directory).  The sticky bit makes it possible to control deletion for
individual files.
</DL>
<P>
The actual bit values of the symbols are listed in the table above
so you can decode file mode values when debugging your programs.
These bit values are correct for most systems, but they are not
guaranteed.
<P>
<STRONG>Warning:</STRONG> Writing explicit numbers for file permissions is bad
practice.  It is not only nonportable, it also requires everyone who
reads your program to remember what the bits mean.  To make your
program clean, use the symbolic names.
<P>
<A NAME="IDX838"></A>
<A NAME="IDX839"></A>
<A NAME="IDX840"></A>
<H3><A NAME="SEC206" HREF="library_toc.html#SEC206" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC206">How Your Access to a File is Decided</A></H3>
<P>
Recall that the operating system normally decides access permission for
a file based on the effective user and group IDs of the process, and its
supplementary group IDs, together with the file's owner, group and
permission bits.  These concepts are discussed in detail in
section <A HREF="library_25.html#SEC431" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_25.html#SEC431">The Persona of a Process</A>.
<P>
If the effective user ID of the process matches the owner user ID of the
file, then permissions for read, write, and execute/search are
controlled by the corresponding "user" (or "owner") bits.  Likewise,
if any of the effective group ID or supplementary group IDs of the
process matches the group owner ID of the file, then permissions are
controlled by the "group" bits.  Otherwise, permissions are controlled
by the "other" bits.
<P>
Privileged users, like <SAMP>`root'</SAMP>, can access any file, regardless of
its file permission bits.  As a special case, for a file to be
executable even for a privileged user, at least one of its execute bits
must be set.
<P>
<H3><A NAME="SEC207" HREF="library_toc.html#SEC207" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC207">Assigning File Permissions</A></H3>
<A NAME="IDX841"></A>
<A NAME="IDX842"></A>
<P>
The primitive functions for creating files (for example, <CODE>open</CODE> or
<CODE>mkdir</CODE>) take a <VAR>mode</VAR> argument, which specifies the file
permissions for the newly created file.  But the specified mode is
modified by the process's <DFN>file creation mask</DFN>, or <DFN>umask</DFN>,
before it is used.
<P>
The bits that are set in the file creation mask identify permissions
that are always to be disabled for newly created files.  For example, if
you set all the "other" access bits in the mask, then newly created
files are not accessible at all to processes in the "other"
category, even if the <VAR>mode</VAR> argument specified to the creation 
function would permit such access.  In other words, the file creation
mask is the complement of the ordinary access permissions you want to
grant.
<P>
Programs that create files typically specify a <VAR>mode</VAR> argument that
includes all the permissions that make sense for the particular file.
For an ordinary file, this is typically read and write permission for
all classes of users.  These permissions are then restricted as
specified by the individual user's own file creation mask.
<A NAME="IDX843"></A>
<P>
To change the permission of an existing file given its name, call
<CODE>chmod</CODE>.  This function ignores the file creation mask; it uses
exactly the specified permission bits.
<A NAME="IDX844"></A>
<P>
In normal use, the file creation mask is initialized in the user's login
shell (using the <CODE>umask</CODE> shell command), and inherited by all
subprocesses.  Application programs normally don't need to worry about
the file creation mask.  It will do automatically what it is supposed to
do.
<P>
When your program should create a file and bypass the umask for its
access permissions, the easiest way to do this is to use <CODE>fchmod</CODE>
after opening the file, rather than changing the umask.
<P>
In fact, changing the umask is usually done only by shells.  They use
the <CODE>umask</CODE> function.
<P>
The functions in this section are declared in <TT>`sys/stat.h'</TT>.
<A NAME="IDX845"></A>
<P>
<A NAME="IDX846"></A>
<U>Function:</U> mode_t <B>umask</B> <I>(mode_t <VAR>mask</VAR>)</I><P>
The <CODE>umask</CODE> function sets the file creation mask of the current
process to <VAR>mask</VAR>, and returns the previous value of the file
creation mask.
<P>
Here is an example showing how to read the mask with <CODE>umask</CODE>
without changing it permanently:
<P>
<PRE>
mode_t
read_umask (void)
{
  mask = umask (0);
  umask (mask);
}
</PRE>
<P>
However, it is better to use <CODE>getumask</CODE> if you just want to read
the mask value, because that is reentrant (at least if you use the GNU
operating system).
<P>
<A NAME="IDX847"></A>
<U>Function:</U> mode_t <B>getumask</B> <I>(void)</I><P>
Return the current value of the file creation mask for the current
process.  This function is a GNU extension.
<P>
<A NAME="IDX848"></A>
<U>Function:</U> int <B>chmod</B> <I>(const char *<VAR>filename</VAR>, mode_t <VAR>mode</VAR>)</I><P>
The <CODE>chmod</CODE> function sets the access permission bits for the file
named by <VAR>filename</VAR> to <VAR>mode</VAR>.
<P>
If the <VAR>filename</VAR> names a symbolic link, <CODE>chmod</CODE> changes the
permission of the file pointed to by the link, not those of the link
itself.  There is actually no way to set the mode of a link, which is
always <CODE>-1</CODE>.
<P>
This function returns <CODE>0</CODE> if successful and <CODE>-1</CODE> if not.  In
addition to the usual file name syntax errors (see section <A HREF="library_10.html#SEC115" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_10.html#SEC115">File Name Errors</A>), the following <CODE>errno</CODE> error conditions are defined for
this function:
<P>
<DL COMPACT>
<DT><CODE>ENOENT</CODE>
<DD>The named file doesn't exist.
<P>
<DT><CODE>EPERM</CODE>
<DD>This process does not have permission to change the access permission of
this file.  Only the file's owner (as judged by the effective user ID of
the process) or a privileged user can change them.
<P>
<DT><CODE>EROFS</CODE>
<DD>The file resides on a read-only file system.
</DL>
<P>
<A NAME="IDX849"></A>
<U>Function:</U> int <B>fchmod</B> <I>(int <VAR>filedes</VAR>, int <VAR>mode</VAR>)</I><P>
This is like <CODE>chmod</CODE>, except that it changes the permissions of
the file currently open via descriptor <VAR>filedes</VAR>.
<P>
The return value from <CODE>fchmod</CODE> is <CODE>0</CODE> on success and <CODE>-1</CODE>
on failure.  The following <CODE>errno</CODE> error codes are defined for this
function:
<P>
<DL