library_13.html

Linux程序员的工作手册

</PRE>
<P>
The order in which files appear in a directory tends to be fairly
random.  A more useful program would sort the entries (perhaps by
alphabetizing them) before printing them; see section <A HREF="library_8.html#SEC89" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_8.html#SEC89">Array Sort Function</A>
<P>
<H3><A NAME="SEC194" HREF="library_toc.html#SEC194" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC194">Random Access in a Directory Stream</A></H3>
<A NAME="IDX744"></A>
<P>
This section describes how to reread parts of a directory that you have
already read from an open directory stream.  All the symbols are
declared in the header file <TT>`dirent.h'</TT>.
<P>
<A NAME="IDX745"></A>
<U>Function:</U> void <B>rewinddir</B> <I>(DIR *<VAR>dirstream</VAR>)</I><P>
The <CODE>rewinddir</CODE> function is used to reinitialize the directory
stream <VAR>dirstream</VAR>, so that if you call <CODE>readdir</CODE> it
returns information about the first entry in the directory again.  This
function also notices if files have been added or removed to the
directory since it was opened with <CODE>opendir</CODE>.  (Entries for these
files might or might not be returned by <CODE>readdir</CODE> if they were
added or removed since you last called <CODE>opendir</CODE> or
<CODE>rewinddir</CODE>.)
<P>
<A NAME="IDX746"></A>
<U>Function:</U> off_t <B>telldir</B> <I>(DIR *<VAR>dirstream</VAR>)</I><P>
The <CODE>telldir</CODE> function returns the file position of the directory
stream <VAR>dirstream</VAR>.  You can use this value with <CODE>seekdir</CODE> to
restore the directory stream to that position.
<P>
<A NAME="IDX747"></A>
<U>Function:</U> void <B>seekdir</B> <I>(DIR *<VAR>dirstream</VAR>, off_t <VAR>pos</VAR>)</I><P>
The <CODE>seekdir</CODE> function sets the file position of the directory
stream <VAR>dirstream</VAR> to <VAR>pos</VAR>.  The value <VAR>pos</VAR> must be the
result of a previous call to <CODE>telldir</CODE> on this particular stream;
closing and reopening the directory can invalidate values returned by
<CODE>telldir</CODE>.
<P>
<A NAME="IDX748"></A>
<A NAME="IDX749"></A>
<A NAME="IDX750"></A>
<A NAME="IDX751"></A>
<H2><A NAME="SEC195" HREF="library_toc.html#SEC195" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC195">Hard Links</A></H2>
<P>
In POSIX systems, one file can have many names at the same time.  All of
the names are equally real, and no one of them is preferred to the
others.
<P>
To add a name to a file, use the <CODE>link</CODE> function.  (The new name is
also called a <DFN>hard link</DFN> to the file.)  Creating a new link to a
file does not copy the contents of the file; it simply makes a new name
by which the file can be known, in addition to the file's existing name
or names.
<P>
One file can have names in several directories, so the the organization
of the file system is not a strict hierarchy or tree.
<P>
Since a particular file exists within a single file system, all its
names must be in directories in that file system.  <CODE>link</CODE> reports
an error if you try to make a hard link to the file from another file
system.
<P>
The prototype for the <CODE>link</CODE> function is declared in the header
file <TT>`unistd.h'</TT>.
<A NAME="IDX752"></A>
<P>
<A NAME="IDX753"></A>
<U>Function:</U> int <B>link</B> <I>(const char *<VAR>oldname</VAR>, const char *<VAR>newname</VAR>)</I><P>
The <CODE>link</CODE> function makes a new link to the existing file named by
<VAR>oldname</VAR>, under the new name <VAR>newname</VAR>.
<P>
This function returns a value of <CODE>0</CODE> if it is successful and
<CODE>-1</CODE> on 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>) for both <VAR>oldname</VAR> and <VAR>newname</VAR>, the
following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EACCES</CODE>
<DD>The directory in which the new link is to be written is not writable.
<P>
<DT><CODE>EEXIST</CODE>
<DD>There is already a file named <VAR>newname</VAR>.  If you want to replace
this link with a new link, you must remove the old link explicitly first.
<P>
<DT><CODE>EMLINK</CODE>
<DD>There are already too many links to the file named by <VAR>oldname</VAR>.
(The maximum number of links to a file is <CODE>LINK_MAX</CODE>; see
section <A HREF="library_27.html#SEC463" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_27.html#SEC463">Limits on File System Capacity</A>.)
<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.  You can't make a link to
a file that doesn't exist.
<P>
<DT><CODE>ENOSPC</CODE>
<DD>The directory or file system that would contain the new link is "full"
and cannot be extended.
<P>
<DT><CODE>EPERM</CODE>
<DD>Some implementations only allow privileged users to make links to
directories, and others prohibit this operation entirely.  This error
is used to report the problem.
<P>
<DT><CODE>EROFS</CODE>
<DD>The directory containing the new link can't be modified because it's on
a read-only file system.
<P>
<DT><CODE>EXDEV</CODE>
<DD>The directory specified in <VAR>newname</VAR> is on a different file system
than the existing file.
</DL>
<P>
<A NAME="IDX754"></A>
<A NAME="IDX755"></A>
<A NAME="IDX756"></A>
<A NAME="IDX757"></A>
<H2><A NAME="SEC196" HREF="library_toc.html#SEC196" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC196">Symbolic Links</A></H2>
<P>
The GNU system supports <DFN>soft links</DFN> or <DFN>symbolic links</DFN>.  This
is a kind of "file" that is essentially a pointer to another file
name.  Unlike hard links, symbolic links can be made to directories or
across file systems with no restrictions.  You can also make a symbolic
link to a name which is not the name of any file.  (Opening this link
will fail until a file by that name is created.)  Likewise, if the
symbolic link points to an existing file which is later deleted, the
symbolic link continues to point to the same file name even though the
name no longer names any file.
<P>
The reason symbolic links work the way they do is that special things
happen when you try to open the link.  The <CODE>open</CODE> function realizes
you have specified the name of a link, reads the file name contained in
the link, and opens that file name instead.  The <CODE>stat</CODE> function
likewise operates on the file that the symbolic link points to, instead
of on the link itself.  So does <CODE>link</CODE>, the function that makes a
hard link.
<P>
By contrast, other operations such as deleting or renaming the file
operate on the link itself.  The functions <CODE>readlink</CODE> and 
<CODE>lstat</CODE> also refrain from following symbolic links, because
their purpose is to obtain information about the link.
<P>
Prototypes for the functions listed in this section are in
<TT>`unistd.h'</TT>.
<A NAME="IDX758"></A>
<P>
<A NAME="IDX759"></A>
<U>Function:</U> int <B>symlink</B> <I>(const char *<VAR>oldname</VAR>, const char *<VAR>newname</VAR>)</I><P>
The <CODE>symlink</CODE> function makes a symbolic link to <VAR>oldname</VAR> named
<VAR>newname</VAR>.
<P>
The normal return value from <CODE>symlink</CODE> is <CODE>0</CODE>.  A return value
of <CODE>-1</CODE> indicates an error.  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>EEXIST</CODE>
<DD>There is already an existing file named <VAR>newname</VAR>.
<P>
<DT><CODE>EROFS</CODE>
<DD>The file <VAR>newname</VAR> would exist on a read-only file system.
<P>
<DT><CODE>ENOSPC</CODE>
<DD>The directory or file system cannot be extended to make the new link.
<P>
<DT><CODE>EIO</CODE>
<DD>A hardware error occurred while reading or writing data on the disk.
<P>
</DL>
<P>
<A NAME="IDX760"></A>
<U>Function:</U> int <B>readlink</B> <I>(const char *<VAR>filename</VAR>, char *<VAR>buffer</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>readlink</CODE> function gets the value of the symbolic link
<VAR>filename</VAR>.  The file name that the link points to is copied into
<VAR>buffer</VAR>.  This file name string is <EM>not</EM> null-terminated;
<CODE>readlink</CODE> normally returns the number of characters copied.  The
<VAR>size</VAR> argument specifies the maximum number of characters to copy,
usually the allocation size of <VAR>buffer</VAR>.
<P>
If the return value equals <VAR>size</VAR>, you cannot tell whether or not
there was room to return the entire name.  So make a bigger buffer and
call <CODE>readlink</CODE> again.  Here is an example:
<P>
<PRE>
char *
readlink_malloc (char *filename)
{
  int size = 100;

  while (1)
    {
      char *buffer = (char *) xmalloc (size);
      int nchars = readlink (filename, buffer, size);
      if (nchars &#60; size)
        return buffer;
      free (buffer);
      size *= 2;
    }
}
</PRE>
<P>
A value of <CODE>-1</CODE> is returned in case of error.  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>EINVAL</CODE>
<DD>The named file is not a symbolic link.
<P>
<DT><CODE>EIO</CODE>
<DD>A hardware error occurred while reading or writing data on the disk.
</DL>
<P>
<A NAME="IDX761"></A>
<A NAME="IDX762"></A>
<A NAME="IDX763"></A>
<H2><A NAME="SEC197" HREF="library_toc.html#SEC197" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC197">Deleting Files</A></H2>
<P>
You can delete a file with the functions <CODE>unlink</CODE> or <CODE>remove</CODE>.
(These names are synonymous.)
<P>
Deletion actually deletes a file name.  If this is the file's only name,
then the file is deleted as well.  If the file has other names as well
(see section <A HREF="library_13.html#SEC195" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC195">Hard Links</A>), it remains accessible under its other names.
<P>
<A NAME="IDX764"></A>
<U>Function:</U> int <B>unlink</B> <I>(const char *<VAR>filename</VAR>)</I><P>
The <CODE>unlink</CODE> function deletes the file name <VAR>filename</VAR>.  If
this is a file's sole name, the file itself is also deleted.  (Actually,
if any process has the file open when this happens, deletion is
postponed until all processes have closed the file.)
<A NAME="IDX765"></A>
<P>
The function <CODE>unlink</CODE> is declared in the header file <TT>`unistd.h'</TT>.
<P>
This function returns <CODE>0</CODE> on successful completion, and <CODE>-1</CODE>
on error.  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>EACCESS</CODE>
<DD>Write permission is denied for the directory from which the file is to be
removed.
<P>
<DT><CODE>EBUSY</CODE>
<DD>This error indicates that the file is being used by the system in such a
way that it can't be unlinked.  Examples of situations where you might
see this error are if the file name specifies the root directory or a
mount point for a file system.
<P>
<DT><CODE>ENOENT</CODE>
<DD>The file name to be deleted doesn't exist.
<P>
<DT><CODE>EPERM</CODE>
<DD>On some systems, <CODE>unlink</CODE> cannot be used to delete the name of a
directory, or can only be used this way by a privileged user.
To avoid such problems, use <CODE>rmdir</CODE> to delete directories.
<P>
<DT><CODE>EROFS</CODE>
<DD>The directory in which the file name is to be deleted is on a read-only
file system, and can't be modified.
</DL>
<P>
<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