   This file documents the GNU C library.

   This is Edition 0.10, last updated 2001-07-06, of `The GNU C Library
Reference Manual', for Version 2.2.x.

   Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002
Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software Needs Free Documentation" and
"GNU Lesser General Public License", the Front-Cover texts being (a)
(see below), and with the Back-Cover Texts being (b) (see below).  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.

File System Interface
*********************

   This chapter describes the GNU C library's functions for manipulating
files.  Unlike the input and output functions (see I/O on Streams;
Low-Level I/O), these functions are concerned with operating on
the files themselves rather than on their contents.

   Among the facilities described in this chapter are functions for
examining or modifying directories, functions for renaming and deleting
files, and functions for examining and setting file attributes such as
access permissions and modification times.

Working Directory
=================

   Each process has associated with it a directory, called its "current
working directory" or simply "working directory", that is used in the
resolution of relative file names (see File Name Resolution).

   When you log in and begin a new session, your working directory is
initially set to the home directory associated with your login account
in the system user database.  You can find any user's home directory
using the `getpwuid' or `getpwnam' functions; see User Database.

   Users can change the working directory using shell commands like
`cd'.  The functions described in this section are the primitives used
by those commands and by other programs for examining and changing the
working directory.

   Prototypes for these functions are declared in the header file
`unistd.h'.

 - Function: char * getcwd (char *BUFFER, size_t SIZE)
     The `getcwd' function returns an absolute file name representing
     the current working directory, storing it in the character array
     BUFFER that you provide.  The SIZE argument is how you tell the
     system the allocation size of BUFFER.

     The GNU library version of this function also permits you to
     specify a null pointer for the BUFFER argument.  Then `getcwd'
     allocates a buffer automatically, as with `malloc' (see
     Unconstrained Allocation).  If the SIZE is greater than zero,
     then the buffer is that large; otherwise, the buffer is as large
     as necessary to hold the result.

     The return value is BUFFER on success and a null pointer on
     failure.  The following `errno' error conditions are defined for
     this function:

    `EINVAL'
          The SIZE argument is zero and BUFFER is not a null pointer.

    `ERANGE'
          The SIZE argument is less than the length of the working
          directory name.  You need to allocate a bigger array and try
          again.

    `EACCES'
          Permission to read or search a component of the file name was
          denied.

   You could implement the behavior of GNU's `getcwd (NULL, 0)' using
only the standard behavior of `getcwd':

     char *
     gnu_getcwd ()
     {
       size_t size = 100;

       while (1)
         {
           char *buffer = (char *) xmalloc (size);
           if (getcwd (buffer, size) == buffer)
             return buffer;
           free (buffer);
           if (errno != ERANGE)
             return 0;
           size *= 2;
         }
     }

See Malloc Examples, for information about `xmalloc', which is not
a library function but is a customary name used in most GNU software.

 - Deprecated Function: char * getwd (char *BUFFER)
     This is similar to `getcwd', but has no way to specify the size of
     the buffer.  The GNU library provides `getwd' only for backwards
     compatibility with BSD.

     The BUFFER argument should be a pointer to an array at least
     `PATH_MAX' bytes long (see Limits for Files).  In the GNU
     system there is no limit to the size of a file name, so this is not
     necessarily enough space to contain the directory name.  That is
     why this function is deprecated.

 - Function: char * get_current_dir_name (void)
     This `get_current_dir_name' function is bascially equivalent to
     `getcwd (NULL, 0)'.  The only difference is that the value of the
     `PWD' variable is returned if this value is correct.  This is a
     subtle difference which is visible if the path described by the
     `PWD' value is using one or more symbol links in which case the
     value returned by `getcwd' can resolve the symbol links and
     therefore yield a different result.

     This function is a GNU extension.

 - Function: int chdir (const char *FILENAME)
     This function is used to set the process's working directory to
     FILENAME.

     The normal, successful return value from `chdir' is `0'.  A value
     of `-1' is returned to indicate an error.  The `errno' error
     conditions defined for this function are the usual file name
     syntax errors (see File Name Errors), plus `ENOTDIR' if the
     file FILENAME is not a directory.

 - Function: int fchdir (int FILEDES)
     This function is used to set the process's working directory to
     directory associated with the file descriptor FILEDES.

     The normal, successful return value from `fchdir' is `0'.  A value
     of `-1' is returned to indicate an error.  The following `errno'
     error conditions are defined for this function:

    `EACCES'
          Read permission is denied for the directory named by
          `dirname'.

    `EBADF'
          The FILEDES argument is not a valid file descriptor.

    `ENOTDIR'
          The file descriptor FILEDES is not associated with a
          directory.

    `EINTR'
          The function call was interrupt by a signal.

    `EIO'
          An I/O error occurred.

Accessing Directories
=====================

   The facilities described in this section let you read the contents
of a directory file.  This is useful if you want your program to list
all the files in a directory, perhaps as part of a menu.

   The `opendir' function opens a "directory stream" whose elements are
directory entries.  You use the `readdir' function on the directory
stream to retrieve these entries, represented as `struct dirent'
objects.  The name of the file for each entry is stored in the `d_name'
member of this structure.  There are obvious parallels here to the
stream facilities for ordinary files, described in I/O on Streams.

Format of a Directory Entry
---------------------------

   This section describes what you find in a single directory entry, as
you might obtain it from a directory stream.  All the symbols are
declared in the header file `dirent.h'.

 - Data Type: struct dirent
     This is a structure type used to return information about directory
     entries.  It contains the following fields:

    `char d_name[]'
          This is the null-terminated file name component.  This is the
          only field you can count on in all POSIX systems.

    `ino_t d_fileno'
          This is the file serial number.  For BSD compatibility, you
          can also refer to this member as `d_ino'.  In the GNU system
          and most POSIX systems, for most files this the same as the
          `st_ino' member that `stat' will return for the file.  See
          File Attributes.

    `unsigned char d_namlen'
          This is the length of the file name, not including the
          terminating null character.  Its type is `unsigned char'
          because that is the integer type of the appropriate size

    `unsigned char d_type'
          This is the type of the file, possibly unknown.  The
          following constants are defined for its value:

         `DT_UNKNOWN'
               The type is unknown.  On some systems this is the only
               value returned.

         `DT_REG'
               A regular file.

         `DT_DIR'
               A directory.

         `DT_FIFO'
               A named pipe, or FIFO.  See FIFO Special Files.

         `DT_SOCK'
               A local-domain socket.

         `DT_CHR'
               A character device.

         `DT_BLK'
               A block device.

          This member is a BSD extension.  The symbol
          `_DIRENT_HAVE_D_TYPE' is defined if this member is available.
          On systems where it is used, it corresponds to the file type
          bits in the `st_mode' member of `struct statbuf'.  If the
          value cannot be determine the member value is DT_UNKNOWN.
          These two macros convert between `d_type' values and
          `st_mode' values:

           - Function: int IFTODT (mode_t MODE)
               This returns the `d_type' value corresponding to MODE.

           - Function: mode_t DTTOIF (int DTYPE)
               This returns the `st_mode' value corresponding to DTYPE.

     This structure may contain additional members in the future.  Their
     availability is always announced in the compilation environment by
     a macro names `_DIRENT_HAVE_D_XXX' where XXX is replaced by the
     name of the new member.  For instance, the member `d_reclen'
     available on some systems is announced through the macro
     `_DIRENT_HAVE_D_RECLEN'.

     When a file has multiple names, each name has its own directory
     entry.  The only way you can tell that the directory entries
     belong to a single file is that they have the same value for the
     `d_fileno' field.

     File attributes such as size, modification times etc., are part of
     the file itself, not of any particular directory entry.  See
     File Attributes.

Opening a Directory Stream
--------------------------

   This section describes how to open a directory stream.  All the
symbols are declared in the header file `dirent.h'.

 - Data Type: DIR
     The `DIR' data type represents a directory stream.

   You shouldn't ever allocate objects of the `struct dirent' or `DIR'
data types, since the directory access functions do that for you.
Instead, you refer to these objects using the pointers returned by the
following functions.

 - Function: DIR * opendir (const char *DIRNAME)
     The `opendir' function opens and returns a directory stream for
     reading the directory whose file name is DIRNAME.  The stream has
     type `DIR *'.

     If unsuccessful, `opendir' returns a null pointer.  In addition to
     the usual file name errors (see File Name Errors), the
     following `errno' error conditions are defined for this function:

    `EACCES'
          Read permission is denied for the directory named by
          `dirname'.

    `EMFILE'
          The process has too many files open.

    `ENFILE'
          The entire system, or perhaps the file system which contains
          the directory, cannot support any additional open files at
          the moment.  (This problem cannot happen on the GNU system.)

     The `DIR' type is typically implemented using a file descriptor,
     and the `opendir' function in terms of the `open' function.  See
     Low-Level I/O.  Directory streams and the underlying file
     descriptors are closed on `exec' (see Executing a File).

   In some situations it can be desirable to get hold of the file
descriptor which is created by the `opendir' call.  For instance, to
switch the current working directory to the directory just read the
`fchdir' function could be used.  Historically the `DIR' type was
exposed and programs could access the fields.  This does not happen in
the GNU C library.  Instead a separate function is provided to allow
access.

 - Function: int dirfd (DIR *DIRSTREAM)
     The function `dirfd' returns the file descriptor associated with
     the directory stream DIRSTREAM.  This descriptor can be used until
     the directory is closed with `closedir'.  If the directory stream
     implementation is not using file descriptors the return value is
     `-1'.

Reading and Closing a Directory Stream
--------------------------------------

   This section describes how to read directory entries from a directory
stream, and how to close the stream when you are done with it.  All the
symbols are declared in the header file `dirent.h'.

 - Function: struct dirent * readdir (DIR *DIRSTREAM)
     This function reads the next entry from the directory.  It normally
     returns a pointer to a structure containing information about the
     file.  This structure is statically allocated and can be rewritten
     by a subsequent call.

     *Portability Note:* On some systems `readdir' may not return
     entries for `.' and `..', even though these are always valid file
     names in any directory.  See File Name Resolution.

     If there are no more entries in the directory or an error is
     detected, `readdir' returns a null pointer.  The following `errno'
     error conditions are defined for this function:

    `EBADF'
          The DIRSTREAM argument is not valid.

     `readdir' is not thread safe.  Multiple threads using `readdir' on
     the same DIRSTREAM may overwrite the return value.  Use
     `readdir_r' when this is critical.

 - Function: int readdir_r (DIR *DIRSTREAM, struct dirent *ENTRY,
          struct dirent **RESULT)
     This function is the reentrant version of `readdir'.  Like
     `readdir' it returns the next entry from the directory.  But to
     prevent conflicts between simultaneously running threads the
     result is not stored in statically allocated memory.  Instead the
     argument ENTRY points to a place to store the result.

     The return value is `0' in case the next entry was read
     successfully.  In this case a pointer to the result is returned in
     *RESULT.  It is not required that *RESULT is the same as ENTRY.
     If something goes wrong while executing `readdir_r' the function
     returns a value indicating the error (as described for `readdir').

     If there are no more directory entries, `readdir_r''s return value
     is `0', and *RESULT is set to `NULL'.

     *Portability Note:* On some systems `readdir_r' may not return a
     NUL terminated string for the file name, even when there is no
     `d_reclen' field in `struct dirent' and the file name is the
     maximum allowed size.  Modern systems all have the `d_reclen'
     field, and on old systems multi-threading is not critical.  In any
     case there is no such problem with the `readdir' function, so that
     even on systems without the `d_reclen' member one could use
     multiple threads by using external locking.

     It is also important to look at the definition of the `struct
     dirent' type.  Simply passing a pointer to an object of this type
     for the second parameter of `readdir_r' might not be enough.  Some
     systems don't define the `d_name' element sufficiently long.  In
     this case the user has to provide additional space.  There must be
     room for at least `NAME_MAX + 1' characters in the `d_name' array.
     Code to call `readdir_r' could look like this:

            union
            {
              struct dirent d;
              char b[offsetof (struct dirent, d_name) + NAME_MAX + 1];
            } u;

            if (readdir_r (dir, &u.d, &res) == 0)
              ...

   To support large filesystems on 32-bit machines there are LFS
variants of the last two functions.

 - Function: struct dirent64 * readdir64 (DIR *DIRSTREAM)
     The `readdir64' function is just like the `readdir' function
     except that it returns a pointer to a record of type `struct
     dirent64'.  Some of the members of this data type (notably `d_ino')
     might have a different size to allow large filesystems.

     In all other aspects this function is equivalent to `readdir'.

 - Function: int readdir64_r (DIR *DIRSTREAM, struct dirent64 *ENTRY,
          struct dirent64 **RESULT)
     The `readdir64_r' function is equivalent to the `readdir_r'
     function except that it takes parameters of base type `struct
     dirent64' instead of `struct dirent' in the second and third
     position.  The same precautions mentioned in the documentation of
     `readdir_r' also apply here.

 - Function: int closedir (DIR *DIRSTREAM)
     This function closes the directory stream DIRSTREAM.  It returns
     `0' on success and `-1' on failure.

     The following `errno' error conditions are defined for this
     function:

    `EBADF'
          The DIRSTREAM argument is not valid.

Simple Program to List a Directory
----------------------------------

   Here's a simple program that prints the names of the files in the
current working directory:

     #include <stddef.h>
     #include <stdio.h>
     #include <sys/types.h>
     #include <dirent.h>

     int
     main (void)
     {
       DIR *dp;
       struct dirent *ep;

       dp = opendir ("./");
       if (dp != NULL)
         {
           while (ep = readdir (dp))
             puts (ep->d_name);
           (void) closedir (dp);
         }
       else
         perror ("Couldn't open the directory");

       return 0;
     }

   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 Scanning Directory Content,
and Array Sort Function.

Random Access in a Directory Stream
-----------------------------------

   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 `dirent.h'.

 - Function: void rewinddir (DIR *DIRSTREAM)
     The `rewinddir' function is used to reinitialize the directory
     stream DIRSTREAM, so that if you call `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 `opendir'.  (Entries for these
     files might or might not be returned by `readdir' if they were
     added or removed since you last called `opendir' or `rewinddir'.)

 - Function: off_t telldir (DIR *DIRSTREAM)
     The `telldir' function returns the file position of the directory
     stream DIRSTREAM.  You can use this value with `seekdir' to
     restore the directory stream to that position.

 - Function: void seekdir (DIR *DIRSTREAM, off_t POS)
     The `seekdir' function sets the file position of the directory
     stream DIRSTREAM to POS.  The value POS must be the result of a
     previous call to `telldir' on this particular stream; closing and
     reopening the directory can invalidate values returned by
     `telldir'.

Scanning the Content of a Directory
-----------------------------------

   A higher-level interface to the directory handling functions is the
`scandir' function.  With its help one can select a subset of the
entries in a directory, possibly sort them and get a list of names as
the result.

 - Function: int scandir (const char *DIR, struct dirent ***NAMELIST,
          int (*SELECTOR) (const struct dirent *), int (*CMP) (const
          void *, const void *))
     The `scandir' function scans the contents of the directory selected
     by DIR.  The result in *NAMELIST is an array of pointers to
     structure of type `struct dirent' which describe all selected
     directory entries and which is allocated using `malloc'.  Instead
     of always getting all directory entries returned, the user supplied
     function SELECTOR can be used to decide which entries are in the
     result.  Only the entries for which SELECTOR returns a non-zero
     value are selected.

     Finally the entries in *NAMELIST are sorted using the
     user-supplied function CMP.  The arguments passed to the CMP
     function are of type `struct dirent **', therefore one cannot
     directly use the `strcmp' or `strcoll' functions; instead see the
     functions `alphasort' and `versionsort' below.

     The return value of the function is the number of entries placed in
     *NAMELIST.  If it is `-1' an error occurred (either the directory
     could not be opened for reading or the malloc call failed) and the
     global variable `errno' contains more information on the error.

   As described above the fourth argument to the `scandir' function
must be a pointer to a sorting function.  For the convenience of the
programmer the GNU C library contains implementations of functions which
are very helpful for this purpose.

 - Function: int alphasort (const void *A, const void *B)
     The `alphasort' function behaves like the `strcoll' function
     (see String/Array Comparison).  The difference is that the
     arguments are not string pointers but instead they are of type
     `struct dirent **'.

     The return value of `alphasort' is less than, equal to, or greater
     than zero depending on the order of the two entries A and B.

 - Function: int versionsort (const void *A, const void *B)
     The `versionsort' function is like `alphasort' except that it uses
     the `strverscmp' function internally.

   If the filesystem supports large files we cannot use the `scandir'
anymore since the `dirent' structure might not able to contain all the
information.  The LFS provides the new type `struct dirent64'.  To use
this we need a new function.

 - Function: int scandir64 (const char *DIR, struct dirent64
          ***NAMELIST, int (*SELECTOR) (const struct dirent64 *), int
          (*CMP) (const void *, const void *))
     The `scandir64' function works like the `scandir' function except
     that the directory entries it returns are described by elements of
     type `struct dirent64'.  The function pointed to by SELECTOR is
     again used to select the desired entries, except that SELECTOR now
     must point to a function which takes a `struct dirent64 *'
     parameter.

     Similarly the CMP function should expect its two arguments to be
     of type `struct dirent64 **'.

   As CMP is now a function of a different type, the functions
`alphasort' and `versionsort' cannot be supplied for that argument.
Instead we provide the two replacement functions below.

 - Function: int alphasort64 (const void *A, const void *B)
     The `alphasort64' function behaves like the `strcoll' function
     (see String/Array Comparison).  The difference is that the
     arguments are not string pointers but instead they are of type
     `struct dirent64 **'.

     Return value of `alphasort64' is less than, equal to, or greater
     than zero depending on the order of the two entries A and B.

 - Function: int versionsort64 (const void *A, const void *B)
     The `versionsort64' function is like `alphasort64', excepted that
     it uses the `strverscmp' function internally.

   It is important not to mix the use of `scandir' and the 64-bit
comparison functions or vice versa.  There are systems on which this
works but on others it will fail miserably.

Simple Program to List a Directory, Mark II
-------------------------------------------

   Here is a revised version of the directory lister found above (see
Simple Directory Lister).  Using the `scandir' function we can avoid
the functions which work directly with the directory contents.  After
the call the returned entries are available for direct use.

     #include <stdio.h>
     #include <dirent.h>

     static int
     one (struct dirent *unused)
     {
       return 1;
     }

     int
     main (void)
     {
       struct dirent **eps;
       int n;

       n = scandir ("./", &eps, one, alphasort);
       if (n >= 0)
         {
           int cnt;
           for (cnt = 0; cnt < n; ++cnt)
             puts (eps[cnt]->d_name);
         }
       else
         perror ("Couldn't open the directory");

       return 0;
     }

   Note the simple selector function in this example.  Since we want to
see all directory entries we always return `1'.

Working with Directory Trees
============================

   The functions described so far for handling the files in a directory
have allowed you to either retrieve the information bit by bit, or to
process all the files as a group (see `scandir').  Sometimes it is
useful to process whole hierarchies of directories and their contained
files.  The X/Open specification defines two functions to do this.  The
simpler form is derived from an early definition in System V systems
and therefore this function is available on SVID-derived systems.  The
prototypes and required definitions can be found in the `ftw.h' header.

   There are four functions in this family: `ftw', `nftw' and their
64-bit counterparts `ftw64' and `nftw64'.  These functions take as one
of their arguments a pointer to a callback function of the appropriate
type.

 - Data Type: __ftw_func_t
          int (*) (const char *, const struct stat *, int)

     The type of callback functions given to the `ftw' function.  The
     first parameter points to the file name, the second parameter to an
     object of type `struct stat' which is filled in for the file named
     in the first parameter.

     The last parameter is a flag giving more information about the
     current file.  It can have the following values:

    `FTW_F'
          The item is either a normal file or a file which does not fit
          into one of the following categories.  This could be special
          files, sockets etc.

    `FTW_D'
          The item is a directory.

    `FTW_NS'
          The `stat' call failed and so the information pointed to by
          the second paramater is invalid.

    `FTW_DNR'
          The item is a directory which cannot be read.

    `FTW_SL'
          The item is a symbolic link.  Since symbolic links are
          normally followed seeing this value in a `ftw' callback
          function means the referenced file does not exist.  The
          situation for `nftw' is different.

          This value is only available if the program is compiled with
          `_BSD_SOURCE' or `_XOPEN_EXTENDED' defined before including
          the first header.  The original SVID systems do not have
          symbolic links.

     If the sources are compiled with `_FILE_OFFSET_BITS == 64' this
     type is in fact `__ftw64_func_t' since this mode changes `struct
     stat' to be `struct stat64'.

   For the LFS interface and for use in the function `ftw64', the
header `ftw.h' defines another function type.

 - Data Type: __ftw64_func_t
          int (*) (const char *, const struct stat64 *, int)

     This type is used just like `__ftw_func_t' for the callback
     function, but this time is called from `ftw64'.  The second
     parameter to the function is a pointer to a variable of type
     `struct stat64' which is able to represent the larger values.

 - Data Type: __nftw_func_t
          int (*) (const char *, const struct stat *, int, struct FTW *)

     The first three arguments are the same as for the `__ftw_func_t'
     type.  However for the third argument some additional values are
     defined to allow finer differentiation:
    `FTW_DP'
          The current item is a directory and all subdirectories have
          already been visited and reported.  This flag is returned
          instead of `FTW_D' if the `FTW_DEPTH' flag is passed to
          `nftw' (see below).

    `FTW_SLN'
          The current item is a stale symbolic link.  The file it
          points to does not exist.

     The last parameter of the callback function is a pointer to a
     structure with some extra information as described below.

     If the sources are compiled with `_FILE_OFFSET_BITS == 64' this
     type is in fact `__nftw64_func_t' since this mode changes `struct
     stat' to be `struct stat64'.

   For the LFS interface there is also a variant of this data type
available which has to be used with the `nftw64' function.

 - Data Type: __nftw64_func_t
          int (*) (const char *, const struct stat64 *, int, struct FTW *)

     This type is used just like `__nftw_func_t' for the callback
     function, but this time is called from `nftw64'.  The second
     parameter to the function is this time a pointer to a variable of
     type `struct stat64' which is able to represent the larger values.

 - Data Type: struct FTW
     The information contained in this structure helps in interpreting
     the name parameter and gives some information about the current
     state of the traversal of the directory hierarchy.

    `int base'
          The value is the offset into the string passed in the first
          parameter to the callback function of the beginning of the
          file name.  The rest of the string is the path of the file.
          This information is especially important if the `FTW_CHDIR'
          flag was set in calling `nftw' since then the current
          directory is the one the current item is found in.

    `int level'
          Whilst processing, the code tracks how many directories down
          it has gone to find the current file.  This nesting level
          starts at 0 for files in the initial directory (or is zero
          for the initial file if a file was passed).

 - Function: int ftw (const char *FILENAME, __ftw_func_t FUNC, int
          DESCRIPTORS)
     The `ftw' function calls the callback function given in the
     parameter FUNC for every item which is found in the directory
     specified by FILENAME and all directories below.  The function
     follows symbolic links if necessary but does not process an item
     twice.  If FILENAME is not a directory then it itself is the only
     object returned to the callback function.

     The file name passed to the callback function is constructed by
     taking the FILENAME parameter and appending the names of all passed
     directories and then the local file name.  So the callback
     function can use this parameter to access the file.  `ftw' also
     calls `stat' for the file and passes that information on to the
     callback function.  If this `stat' call was not successful the
     failure is indicated by setting the third argument of the callback
     function to `FTW_NS'.  Otherwise it is set according to the
     description given in the account of `__ftw_func_t' above.

     The callback function is expected to return 0 to indicate that no
     error occurred and that processing should continue.  If an error
     occurred in the callback function or it wants `ftw' to return
     immediately, the callback function can return a value other than
     0.  This is the only correct way to stop the function.  The
     program must not use `setjmp' or similar techniques to continue
     from another place.  This would leave resources allocated by the
     `ftw' function unfreed.

     The DESCRIPTORS parameter to `ftw' specifies how many file
     descriptors it is allowed to consume.  The function runs faster
     the more descriptors it can use.  For each level in the directory
     hierarchy at most one descriptor is used, but for very deep ones
     any limit on open file descriptors for the process or the system
     may be exceeded.  Moreover, file descriptor limits in a
     multi-threaded program apply to all the threads as a group, and
     therefore it is a good idea to supply a reasonable limit to the
     number of open descriptors.

     The return value of the `ftw' function is 0 if all callback
     function calls returned 0 and all actions performed by the `ftw'
     succeeded.  If a function call failed (other than calling `stat'
     on an item) the function returns -1.  If a callback function
     returns a value other than 0 this value is returned as the return
     value of `ftw'.

     When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a
     32-bit system this function is in fact `ftw64', i.e. the LFS
     interface transparently replaces the old interface.

 - Function: int ftw64 (const char *FILENAME, __ftw64_func_t FUNC, int
          DESCRIPTORS)
     This function is similar to `ftw' but it can work on filesystems
     with large files.  File information is reported using a variable
     of type `struct stat64' which is passed by reference to the
     callback function.

     When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a
     32-bit system this function is available under the name `ftw' and
     transparently replaces the old implementation.

 - Function: int nftw (const char *FILENAME, __nftw_func_t FUNC, int
          DESCRIPTORS, int FLAG)
     The `nftw' function works like the `ftw' functions.  They call the
     callback function FUNC for all items found in the directory
     FILENAME and below.  At most DESCRIPTORS file descriptors are
     consumed during the `nftw' call.

     One difference is that the callback function is of a different
     type.  It is of type `struct FTW *' and provides the callback
     function with the extra information described above.

     A second difference is that `nftw' takes a fourth argument, which
     is 0 or a bitwise-OR combination of any of the following values.

    `FTW_PHYS'
          While traversing the directory symbolic links are not
          followed.  Instead symbolic links are reported using the
          `FTW_SL' value for the type parameter to the callback
          function.  If the file referenced by a symbolic link does not
          exist `FTW_SLN' is returned instead.

    `FTW_MOUNT'
          The callback function is only called for items which are on
          the same mounted filesystem as the directory given by the
          FILENAME parameter to `nftw'.

    `FTW_CHDIR'
          If this flag is given the current working directory is
          changed to the directory of the reported object before the
          callback function is called.  When `ntfw' finally returns the
          current directory is restored to its original value.

    `FTW_DEPTH'
          If this option is specified then all subdirectories and files
          within them are processed before processing the top directory
          itself (depth-first processing).  This also means the type
          flag given to the callback function is `FTW_DP' and not
          `FTW_D'.

     The return value is computed in the same way as for `ftw'.  `nftw'
     returns 0 if no failures occurred and all callback functions
     returned 0.  In case of internal errors, such as memory problems,
     the return value is -1 and ERRNO is set accordingly.  If the
     return value of a callback invocation was non-zero then that value
     is returned.

     When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a
     32-bit system this function is in fact `nftw64', i.e. the LFS
     interface transparently replaces the old interface.

 - Function: int nftw64 (const char *FILENAME, __nftw64_func_t FUNC,
          int DESCRIPTORS, int FLAG)
     This function is similar to `nftw' but it can work on filesystems
     with large files.  File information is reported using a variable
     of type `struct stat64' which is passed by reference to the
     callback function.

     When the sources are compiled with `_FILE_OFFSET_BITS == 64' on a
     32-bit system this function is available under the name `nftw' and
     transparently replaces the old implementation.

Hard Links
==========

   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 `link' function.  (The new name is
also called a "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 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.  `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 `link' function is declared in the header file
`unistd.h'.

 - Function: int link (const char *OLDNAME, const char *NEWNAME)
     The `link' function makes a new link to the existing file named by
     OLDNAME, under the new name NEWNAME.

     This function returns a value of `0' if it is successful and `-1'
     on failure.  In addition to the usual file name errors (see File Name Errors)
     for both OLDNAME and NEWNAME, the following `errno'
     error conditions are defined for this function:

    `EACCES'
          You are not allowed to write to the directory in which the
          new link is to be written.

    `EEXIST'
          There is already a file named NEWNAME.  If you want to replace
          this link with a new link, you must remove the old link
          explicitly first.

    `EMLINK'
          There are already too many links to the file named by OLDNAME.
          (The maximum number of links to a file is `LINK_MAX'; see
          Limits for Files.)

    `ENOENT'
          The file named by OLDNAME doesn't exist.  You can't make a
          link to a file that doesn't exist.

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

    `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.

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

    `EXDEV'
          The directory specified in NEWNAME is on a different file
          system than the existing file.

    `EIO'
          A hardware error occurred while trying to read or write the
          to filesystem.

Symbolic Links
==============

   The GNU system supports "soft links" or "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 `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 `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 `readlink' and `lstat' also
refrain from following symbolic links, because their purpose is to
obtain information about the link.  `link', the function that makes a
hard link, does too.  It makes a hard link to the symbolic link, which
one rarely wants.

   Some systems have for some functions operating on files have a limit
on how many symbolic links are followed when resolving a path name.  The
limit if it exists is published in the `sys/param.h' header file.

 - Macro: int MAXSYMLINKS
     The macro `MAXSYMLINKS' specifies how many symlinks some function
     will follow before returning `ELOOP'.  Not all functions behave the
     same and this value is not the same a that returned for
     `_SC_SYMLOOP' by `sysconf'.  In fact, the `sysconf' result can
     indicate that there is no fixed limit although `MAXSYMLINKS'
     exists and has a finite value.

   Prototypes for most of the functions listed in this section are in
`unistd.h'.

 - Function: int symlink (const char *OLDNAME, const char *NEWNAME)
     The `symlink' function makes a symbolic link to OLDNAME named
     NEWNAME.

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

    `EEXIST'
          There is already an existing file named NEWNAME.

    `EROFS'
          The file NEWNAME would exist on a read-only file system.

    `ENOSPC'
          The directory or file system cannot be extended to make the
          new link.

    `EIO'
          A hardware error occurred while reading or writing data on
          the disk.

 - Function: int readlink (const char *FILENAME, char *BUFFER, size_t
          SIZE)
     The `readlink' function gets the value of the symbolic link
     FILENAME.  The file name that the link points to is copied into
     BUFFER.  This file name string is _not_ null-terminated;
     `readlink' normally returns the number of characters copied.  The
     SIZE argument specifies the maximum number of characters to copy,
     usually the allocation size of BUFFER.

     If the return value equals SIZE, you cannot tell whether or not
     there was room to return the entire name.  So make a bigger buffer
     and call `readlink' again.  Here is an example:

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

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

     A value of `-1' is returned in case of error.  In addition to the
     usual file name errors (see File Name Errors), the following
     `errno' error conditions are defined for this function:

    `EINVAL'
          The named file is not a symbolic link.

    `EIO'
          A hardware error occurred while reading or writing data on
          the disk.

   In some situations it is desirable to resolve all the to get the real
name of a file where no prefix names a symbolic link which is followed
and no filename in the path is `.' or `..'.  This is for instance
desirable if files have to be compare in which case different names can
refer to the same inode.

 - Function: char * canonicalize_file_name (const char *NAME)
     The `canonicalize_file_name' function returns the absolute name of
     the file named by NAME which contains no `.', `..' components nor
     any repeated path separators (`/') or symlinks.  The result is
     passed back as the return value of the function in a block of
     memory allocated with `malloc'.  If the result is not used anymore
     the memory should be freed with a call to `free'.

     In any of the path components except the last one is missing the
     function returns a NULL pointer.  This is also what is returned if
     the length of the path reaches or exceeds `PATH_MAX' characters.
     In any case `errno' is set accordingly.

    `ENAMETOOLONG'
          The resulting path is too long.  This error only occurs on
          systems which have a limit on the file name length.

    `EACCES'
          At least one of the path components is not readable.

    `ENOENT'
          The input file name is empty.

    `ENOENT'
          At least one of the path components does not exist.

    `ELOOP'
          More than `MAXSYMLINKS' many symlinks have been followed.

     This function is a GNU extension and is declared in `stdlib.h'.

   The Unix standard includes a similar function which differs from
`canonicalize_file_name' in that the user has to provide the buffer
where the result is placed in.

 - Function: char * realpath (const char *restrict NAME, char *restrict
          RESOLVED)
     The `realpath' function behaves just like `canonicalize_file_name'
     but instead of allocating a buffer for the result it is placed in
     the buffer pointed to by RESOLVED.

     One other difference is that the buffer RESOLVED will contain the
     part of the path component which does not exist or is not readable
     if the function returns `NULL' and `errno' is set to `EACCES' or
     `ENOENT'.

     This function is declared in `stdlib.h'.

   The advantage of using this function is that it is more widely
available.  The drawback is that it reports failures for long path on
systems which have no limits on the file name length.