<A NAME="IDX766"></A>
<U>Function:</U> int <B>remove</B> <I>(const char *<VAR>filename</VAR>)</I><P>
The <CODE>remove</CODE> function is another name for <CODE>unlink</CODE>.
<CODE>remove</CODE> is the ANSI C name, whereas <CODE>unlink</CODE> is the POSIX.1
name.  The name <CODE>remove</CODE> is declared in <TT>`stdio.h'</TT>.
<A NAME="IDX767"></A>
<P>
<A NAME="IDX768"></A>
<A NAME="IDX769"></A>
<A NAME="IDX770"></A>
<U>Function:</U> int <B>rmdir</B> <I>(const char *<VAR>filename</VAR>)</I><P>
The <CODE>rmdir</CODE> function deletes a directory.  The directory must be
empty before it can be removed; in other words, it can only contain
entries for <TT>`.'</TT> and <TT>`..'</TT>.
<P>
In most other respects, <CODE>rmdir</CODE> behaves like <CODE>unlink</CODE>.  There
are two additional <CODE>errno</CODE> error conditions defined for
<CODE>rmdir</CODE>:
<P>
<DL COMPACT>
<DT><CODE>EEXIST</CODE>
<DD><DT><CODE>ENOTEMPTY</CODE>
<DD>The directory to be deleted is not empty.  
</DL>
<P>
These two error codes are synonymous; some systems use one, and some
use the other.
<P>
The prototype for this function is declared in the header file
<TT>`unistd.h'</TT>.
<A NAME="IDX771"></A>
<P>
<H2><A NAME="SEC198" HREF="library_toc.html#SEC198" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC198">Renaming Files</A></H2>
<P>
The <CODE>rename</CODE> function is used to change a file's name.
<A NAME="IDX772"></A>
<P>
<A NAME="IDX773"></A>
<U>Function:</U> int <B>rename</B> <I>(const char *<VAR>oldname</VAR>, const char *<VAR>newname</VAR>)</I><P>
The <CODE>rename</CODE> function renames the file name <VAR>oldname</VAR> with
<VAR>newname</VAR>.  The file formerly accessible under the name
<VAR>oldname</VAR> is afterward accessible as <VAR>newname</VAR> instead.  (If the
file had any other names aside from <VAR>oldname</VAR>, it continues to have
those names.)
<P>
The directory containing the name <VAR>newname</VAR> must be on the same
file system as the file (as indicated by the name <VAR>oldname</VAR>).
<P>
One special case for <CODE>rename</CODE> is when <VAR>oldname</VAR> and
<VAR>newname</VAR> are two names for the same file.  The consistent way to
handle this case is to delete <VAR>oldname</VAR>.  However, POSIX says that
in this case <CODE>rename</CODE> does nothing and reports success--which is
inconsistent.  We don't know what your operating system will do.  The
GNU system, when completed, will probably do the right thing (delete
<VAR>oldname</VAR>) unless you explicitly request strict POSIX compatibility
"even when it hurts".
<P>
If the <VAR>oldname</VAR> is not a directory, then any existing file named
<VAR>newname</VAR> is removed during the renaming operation.  However, if
<VAR>newname</VAR> is the name of a directory, <CODE>rename</CODE> fails in this
case.
<P>
If the <VAR>oldname</VAR> is a directory, then either <VAR>newname</VAR> must not
exist or it must name a directory that is empty.  In the latter case,
the existing directory named <VAR>newname</VAR> is deleted first.  The name
<VAR>newname</VAR> must not specify a subdirectory of the directory
<CODE>oldname</CODE> which is being renamed.
<P>
One useful feature of <CODE>rename</CODE> is that the meaning of the name
<VAR>newname</VAR> changes "atomically" from any previously existing file
by that name to its new meaning (the file that was called
<VAR>oldname</VAR>).  There is no instant at which <VAR>newname</VAR> is
nonexistent "in between" the old meaning and the new meaning.
<P>
If <CODE>rename</CODE> fails, it returns <CODE>-1</CODE>.  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>EACCES</CODE>
<DD>One of the directories containing <VAR>newname</VAR> or <VAR>oldname</VAR>
refuses write permission; or <VAR>newname</VAR> and <VAR>oldname</VAR> are
directories and write permission is refused for one of them.
<P>
<DT><CODE>EBUSY</CODE>
<DD>A directory named by <VAR>oldname</VAR> or <VAR>newname</VAR> is being used by
the system in a way that prevents the renaming from working.  This includes
directories that are mount points for filesystems, and directories
that are the current working directories of processes.
<P>
<DT><CODE>EEXIST</CODE>
<DD>The directory <VAR>newname</VAR> isn't empty.
<P>
<DT><CODE>ENOTEMPTY</CODE>
<DD>The directory <VAR>newname</VAR> isn't empty.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>oldname</VAR> is a directory that contains <VAR>newname</VAR>.
<P>
<DT><CODE>EISDIR</CODE>
<DD>The <VAR>newname</VAR> names a directory, but the <VAR>oldname</VAR> doesn't.
<P>
<DT><CODE>EMLINK</CODE>
<DD>The parent directory of <VAR>newname</VAR> would have too many links.
<P>
Well-designed file systems never report this error, because they permit
more links than your disk could possibly hold.  However, you must still
take account of the possibility of this error, as it could result from
network access to a file system on another machine.
<P>
<DT><CODE>ENOENT</CODE>
<DD>The file named by <VAR>oldname</VAR> doesn't exist.
<P>
<DT><CODE>ENOSPC</CODE>
<DD>The directory that would contain <VAR>newname</VAR> has no room for another
entry, and there is no space left in the file system to expand it.
<P>
<DT><CODE>EROFS</CODE>
<DD>The operation would involve writing to a directory on a read-only file
system.
<P>
<DT><CODE>EXDEV</CODE>
<DD>The two file names <VAR>newname</VAR> and <VAR>oldnames</VAR> are on different
file systems.
</DL>
<P>
<A NAME="IDX774"></A>
<A NAME="IDX775"></A>
<H2><A NAME="SEC199" HREF="library_toc.html#SEC199" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC199">Creating Directories</A></H2>
<A NAME="IDX776"></A>
<P>
Directories are created with the <CODE>mkdir</CODE> function.  (There is also
a shell command <CODE>mkdir</CODE> which does the same thing.)
<P>
<A NAME="IDX777"></A>
<U>Function:</U> int <B>mkdir</B> <I>(const char *<VAR>filename</VAR>, mode_t <VAR>mode</VAR>)</I><P>
The <CODE>mkdir</CODE> function creates a new, empty directory whose name is
<VAR>filename</VAR>.
<P>
The argument <VAR>mode</VAR> specifies the file permissions for the new
directory file.  See section <A HREF="library_13.html#SEC205" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC205">The Mode Bits for Access Permission</A>, for more information about
this.
<P>
A return value of <CODE>0</CODE> indicates successful completion, and
<CODE>-1</CODE> indicates failure.  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>EACCES</CODE>
<DD>Write permission is denied for the parent directory in which the new
directory is to be added.
<P>
<DT><CODE>EEXIST</CODE>
<DD>A file named <VAR>filename</VAR> already exists.
<P>
<DT><CODE>EMLINK</CODE>
<DD>The parent directory has too many links.
<P>
Well-designed file systems never report this error, because they permit
more links than your disk could possibly hold.  However, you must still
take account of the possibility of this error, as it could result from
network access to a file system on another machine.
<P>
<DT><CODE>ENOSPC</CODE>
<DD>The file system doesn't have enough room to create the new directory.
<P>
<DT><CODE>EROFS</CODE>
<DD>The parent directory of the directory being created is on a read-only
file system, and cannot be modified.
</DL>
<P>
To use this function, your program should include the header file
<TT>`sys/stat.h'</TT>.
<A NAME="IDX778"></A>
<P>
<H2><A NAME="SEC200" HREF="library_toc.html#SEC200" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC200">File Attributes</A></H2>
<A NAME="IDX779"></A>
<P>
When you issue an <SAMP>`ls -l'</SAMP> shell command on a file, it gives you
information about the size of the file, who owns it, when it was last
modified, and the like.  This kind of information is called the
<DFN>file attributes</DFN>; it is associated with the file itself and not a
particular one of its names.
<P>
This section contains information about how you can inquire about and
modify these attributes of files.
<P>
<A NAME="IDX780"></A>
<A NAME="IDX781"></A>
<A NAME="IDX782"></A>
<H3><A NAME="SEC201" HREF="library_toc.html#SEC201" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC201">What the File Attribute Values Mean</A></H3>
<P>
When you read the attributes of a file, they come back in a structure
called <CODE>struct stat</CODE>.  This section describes the names of the
attributes, their data types, and what they mean.  For the functions
to read the attributes of a file, see section <A HREF="library_13.html#SEC202" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC202">Reading the Attributes of a File</A>.
<P>
The header file <TT>`sys/stat.h'</TT> declares all the symbols defined
in this section.
<A NAME="IDX783"></A>
<P>
<A NAME="IDX784"></A>
<U>Data Type:</U> <B>struct stat</B><P>
The <CODE>stat</CODE> structure type is used to return information about the
attributes of a file.  It contains at least the following members:
<P>
<DL COMPACT>
<DT><CODE>mode_t st_mode</CODE>
<DD>Specifies the mode of the file.  This includes file type information
(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>) and the file permission bits
(see section <A HREF="library_13.html#SEC205" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC205">The Mode Bits for Access Permission</A>).
<P>
<DT><CODE>ino_t st_ino</CODE>
<DD>The file serial number, which distinguishes this file from all other
files on the same device.
<P>
<DT><CODE>dev_t st_dev</CODE>
<DD>Identifies the device containing the file.  The <CODE>st_ino</CODE> and
<CODE>st_dev</CODE>, taken together, uniquely identify the file.
<P>
<DT><CODE>nlink_t st_nlink</CODE>
<DD>The number of hard links to the file.  This count keeps track of how many
directories have entries for this file.  If the count is ever
decremented to zero, then the file itself is discarded.  Symbolic links
are not counted in the total.
<P>
<DT><CODE>uid_t st_uid</CODE>
<DD>The user ID of the file's owner.  See section <A HREF="library_13.html#SEC204" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC204">File Owner</A>.
<P>
<DT><CODE>gid_t st_gid</CODE>
<DD>The group ID of the file.  See section <A HREF="library_13.html#SEC204" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC204">File Owner</A>.
<P>
<DT><CODE>off_t st_size</CODE>
<DD>This specifies the size of a regular file in bytes.  For files that
are really devices and the like, this field isn't usually meaningful.
<P>
<DT><CODE>time_t st_atime</CODE>
<DD>This is the last access time for the file.  See section <A HREF="library_13.html#SEC209" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC209">File Times</A>.
<P>
<DT><CODE>unsigned long int st_atime_usec</CODE>
<DD>This is the fractional part of the last access time for the file.
See section <A HREF="library_13.html#SEC209" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC209">File Times</A>.
<P>
<DT><CODE>time_t st_mtime</CODE>
<DD>This is the time of the last modification to the contents of the file.
See section <A HREF="library_13.html#SEC209" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC209">File Times</A>.
<P>
<DT><CODE>unsigned long int st_mtime_usec</CODE>
<DD>This is the fractional part of the time of last modification to the
contents of the file.  See section <A HREF="library_13.html#SEC209" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC209">File Times</A>.
<P>
<DT><CODE>time_t st_ctime</CODE>
<DD>This is the time of the last modification to the attributes of the file.
See section <A HREF="library_13.html#SEC209" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC209">File Times</A>.
<P>
<DT><CODE>unsigned long int st_ctime_usec</CODE>
<DD>This is the fractional part of the time of last modification to the
attributes of the file.  See section <A HREF="library_13.html#SEC209" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC209">File Times</A>.
<P>
<DT><CODE>unsigned int st_nblocks</CODE>
<DD>This is the amount of disk space that the file occupies, measured in
units of 512-byte blocks.
<P>
The number of disk blocks is not strictly proportional to the size of
the file, for two reasons: the file system may use some blocks for
internal record keeping; and the file may be sparse--it may have
"holes" which contain zeros but do not actually take up space on the
disk.
<P>
You can tell (approximately) whether a file is sparse by comparing this
value with <CODE>st_size</CODE>, like this:
<P>
<PRE>