filesys.texi

一个C源代码分析器

@comment POSIX.1
@deftypefun void rewinddir (DIR *@var{dirstream})
The @code{rewinddir} function is used to reinitialize the directory
stream @var{dirstream}, so that if you call @code{readdir} 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}.  (Entries for these
files might or might not be returned by @code{readdir} if they were
added or removed since you last called @code{opendir} or
@code{rewinddir}.)
@end deftypefun

@comment dirent.h
@comment BSD
@deftypefun off_t telldir (DIR *@var{dirstream})
The @code{telldir} function returns the file position of the directory
stream @var{dirstream}.  You can use this value with @code{seekdir} to
restore the directory stream to that position.
@end deftypefun

@comment dirent.h
@comment BSD
@deftypefun void seekdir (DIR *@var{dirstream}, off_t @var{pos})
The @code{seekdir} function sets the file position of the directory
stream @var{dirstream} to @var{pos}.  The value @var{pos} must be the
result of a previous call to @code{telldir} on this particular stream;
closing and reopening the directory can invalidate values returned by
@code{telldir}.
@end deftypefun

@node Hard Links
@section Hard Links
@cindex hard link
@cindex link, hard
@cindex multiple names for one file
@cindex file names, multiple

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.

To add a name to a file, use the @code{link} function.  (The new name is
also called a @dfn{hard link} 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.

One file can have names in several directories, so the the organization
of the file system is not a strict hierarchy or tree.

In most implementations, it is not possible to have hard links to the
same file in multiple file systems.  @code{link} reports an error if you
try to make a hard link to the file from another file system when this
cannot be done.

The prototype for the @code{link} function is declared in the header
file @file{unistd.h}.
@pindex unistd.h

@comment unistd.h
@comment POSIX.1
@deftypefun int link (const char *@var{oldname}, const char *@var{newname})
The @code{link} function makes a new link to the existing file named by
@var{oldname}, under the new name @var{newname}.

This function returns a value of @code{0} if it is successful and
@code{-1} on failure.  In addition to the usual file name syntax errors
(@pxref{File Name Errors}) for both @var{oldname} and @var{newname}, the
following @code{errno} error conditions are defined for this function:

@table @code
@item EACCES
The directory in which the new link is to be written is not writable.
@ignore 
Some implementations also require that the existing file be accessible
by the caller, and use this error to report failure for that reason.
@end ignore

@item EEXIST
There is already a file named @var{newname}.  If you want to replace
this link with a new link, you must remove the old link explicitly first.

@item EMLINK
There are already too many links to the file named by @var{oldname}.
(The maximum number of links to a file is @code{LINK_MAX}; see
@ref{Limits for Files}.)

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.

@item ENOENT
The file named by @var{oldname} doesn't exist.  You can't make a link to
a file that doesn't exist.

@item ENOSPC
The directory or file system that would contain the new link is ``full''
and cannot be extended.

@item EPERM
In the GNU system and some others, you cannot make links to directories.
many systems allow only privileged users to do so.  This error
is used to report the problem.

@item EROFS
The directory containing the new link can't be modified because it's on
a read-only file system.

@item EXDEV
The directory specified in @var{newname} is on a different file system
than the existing file.
@end table
@end deftypefun

@node Symbolic Links
@section Symbolic Links
@cindex soft link
@cindex link, soft
@cindex symbolic link
@cindex link, symbolic

The GNU system supports @dfn{soft links} or @dfn{symbolic links}.  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.

The reason symbolic links work the way they do is that special things
happen when you try to open the link.  The @code{open} 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} function
likewise operates on the file that the symbolic link points to, instead
of on the link itself.

By contrast, other operations such as deleting or renaming the file
operate on the link itself.  The functions @code{readlink} and
@code{lstat} also refrain from following symbolic links, because their
purpose is to obtain information about the link.  So does @code{link},
the function that makes a hard link--it makes a hard link to the
symbolic link, which one rarely wants.

Prototypes for the functions listed in this section are in
@file{unistd.h}.
@pindex unistd.h

@comment unistd.h
@comment BSD
@deftypefun int symlink (const char *@var{oldname}, const char *@var{newname})
The @code{symlink} function makes a symbolic link to @var{oldname} named
@var{newname}.

The normal return value from @code{symlink} is @code{0}.  A return value
of @code{-1} indicates an error.  In addition to the usual file name
syntax errors (@pxref{File Name Errors}), the following @code{errno}
error conditions are defined for this function:

@table @code
@item EEXIST
There is already an existing file named @var{newname}.

@item EROFS
The file @var{newname} would exist on a read-only file system.

@item ENOSPC
The directory or file system cannot be extended to make the new link.

@item EIO
A hardware error occurred while reading or writing data on the disk.

@ignore
@comment not sure about these
@item ELOOP
There are too many levels of indirection.  This can be the result of
circular symbolic links to directories.

@item EDQUOT
The new link can't be created because the user's disk quota has been
exceeded.
@end ignore
@end table
@end deftypefun

@comment unistd.h
@comment BSD
@deftypefun int readlink (const char *@var{filename}, char *@var{buffer}, size_t @var{size})
The @code{readlink} function gets the value of the symbolic link
@var{filename}.  The file name that the link points to is copied into
@var{buffer}.  This file name string is @emph{not} null-terminated;
@code{readlink} normally returns the number of characters copied.  The
@var{size} argument specifies the maximum number of characters to copy,
usually the allocation size of @var{buffer}.

If the return value equals @var{size}, you cannot tell whether or not
there was room to return the entire name.  So make a bigger buffer and
call @code{readlink} again.  Here is an example:

@smallexample
char *
readlink_malloc (char *filename)
@{
  int size = 100;

  while (1)
    @{
      char *buffer = (char *) xmalloc (size);
      int nchars = readlink (filename, buffer, size);
      if (nchars < size)
        return buffer;
      free (buffer);
      size *= 2;
    @}
@}
@end smallexample

@c @group  Invalid outside example.
A value of @code{-1} is returned in case of error.  In addition to the
usual file name syntax errors (@pxref{File Name Errors}), the following
@code{errno} error conditions are defined for this function:

@table @code
@item EINVAL
The named file is not a symbolic link.

@item EIO
A hardware error occurred while reading or writing data on the disk.
@end table
@c @end group
@end deftypefun

@node Deleting Files
@section Deleting Files
@cindex deleting a file
@cindex removing a file
@cindex unlinking a file

You can delete a file with the functions @code{unlink} or @code{remove}.

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
(@pxref{Hard Links}), it remains accessible under its other names.

@comment unistd.h
@comment POSIX.1
@deftypefun int unlink (const char *@var{filename})
The @code{unlink} function deletes the file name @var{filename}.  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.)

@pindex unistd.h
The function @code{unlink} is declared in the header file @file{unistd.h}.

This function returns @code{0} on successful completion, and @code{-1}
on error.  In addition to the usual file name syntax errors
(@pxref{File Name Errors}), the following @code{errno} error conditions are 
defined for this function:

@table @code
@item EACCES
Write permission is denied for the directory from which the file is to be
removed.

@item EBUSY
This error indicates that the file is being used by the system in such a
way that it can't be unlinked.  For example, you might see this error if
the file name specifies the root directory or a mount point for a file
system.

@item ENOENT
The file name to be deleted doesn't exist.

@item EPERM
On some systems, @code{unlink} 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} to delete directories.
The GNU system 

@item EROFS
The directory in which the file name is to be deleted is on a read-only
file system, and can't be modified.
@end table
@end deftypefun

@comment unistd.h
@comment POSIX.1
@deftypefun int rmdir (const char *@var{filename})
@cindex directories, deleting
@cindex deleting a directory
The @code{rmdir} function deletes a directory.  The directory must be
empty before it can be removed; in other words, it can only contain
entries for @file{.} and @file{..}.

In most other respects, @code{rmdir} behaves like @code{unlink}.  There
are two additional @code{errno} error conditions defined for
@code{rmdir}:

@table @code
@item ENOTEMPTY
@itemx EEXIST
The directory to be deleted is not empty.  
@end table

These two error codes are synonymous; some systems use one, and some use
the other.  The GNU system always uses @code{ENOTEMPTY}.

The prototype for this function is declared in the header file
@file{unistd.h}.
@pindex unistd.h
@end deftypefun

@comment stdio.h
@comment ANSI
@deftypefun int remove (const char *@var{filename})
This is the ANSI C function to remove a file.  It works like
@code{unlink} for files and like @code{rmdir} for directories.
@code{remove} is declared in @file{stdio.h}.
@pindex stdio.h
@end deftypefun

@node Renaming Files
@section Renaming Files

The @code{rename} function is used to change a file's name.

@cindex renaming a file
@comment stdio.h
@comment ANSI
@deftypefun int rename (const char *@var{oldname}, const char *@var{newname})
The @code{rename} function renames the file name @var{oldname} with
@var{newname}.  The file formerly accessible under the name
@var{oldname} is afterward accessible as @var{newname} instead.  (If the
file had any other names aside from @var{oldname}, it continues to have
those names.)

The directory containing the name @var{newname} must be on the same
file system as the file (as indicated by the name @var{oldname}).

One special case for @code{rename} is when @var{oldname} and
@var{newname} are two names for the same file.  The consistent way to
handle this case is to delete @var{oldname}.  However, POSIX requires
that in this case @code{rename} do nothing and report success---which is
inconsistent.  We don't know what your operating system will do.

If the @var{oldname} is not a directory, then any existing file named
@var{newname} is removed during the renaming operation.  However, if
@var{newname} is the name of a directory, @code{rename} fails in this
case.

If the @var{oldname} is a directory, then either @var{newname} must not
exist or it must name a directory that is empty.  In the latter case,
the existing directory named @var{newname} is deleted first.  The name
@var{newname} must not specify a subdirectory of the directory
@code{oldname} which is being renamed.

One useful feature of @code{rename} is that the meaning of the name
@var{newname} changes ``atomically'' from any previously existing file
by that name to its new meaning (the file that was called
@var{oldname}).  There is no instant at which @var{newname} is
nonexistent ``in between'' the old meaning and the new meaning.  If
there is a system crash during the operation, it is possible for both
names to still exist; but @var{newname} will always be intact if it
exists at all.

If @code{rename} fails, it returns @code{-1}.  In addition to the usual
file name syntax errors (@pxref{File Name Errors}), the following
@code{errno} error conditions are defined for this function: