1: @node File System Interface, Pipes and FIFOs, Low-Level I/O, Top
    2: @c %MENU% Functions for manipulating files
    3: @chapter File System Interface
    4: 
    5: This chapter describes the GNU C library's functions for manipulating
    6: files.  Unlike the input and output functions (@pxref{I/O on Streams};
    7: @pxref{Low-Level I/O}), these functions are concerned with operating
    8: on the files themselves rather than on their contents.
    9: 
   10: Among the facilities described in this chapter are functions for
   11: examining or modifying directories, functions for renaming and deleting
   12: files, and functions for examining and setting file attributes such as
   13: access permissions and modification times.
   14: 
   15: @menu
   16: * Working Directory::           This is used to resolve relative
   17:                                  file names.
   18: * Accessing Directories::       Finding out what files a directory
   19:                                  contains.
   20: * Working with Directory Trees:: Apply actions to all files or a selectable
   21:                                  subset of a directory hierarchy.
   22: * Hard Links::                  Adding alternate names to a file.
   23: * Symbolic Links::              A file that ``points to'' a file name.
   24: * Deleting Files::              How to delete a file, and what that means.
   25: * Renaming Files::              Changing a file's name.
   26: * Creating Directories::        A system call just for creating a directory.
   27: * File Attributes::             Attributes of individual files.
   28: * Making Special Files::        How to create special files.
   29: * Temporary Files::             Naming and creating temporary files.
   30: @end menu
   31: 
   32: @node Working Directory
   33: @section Working Directory
   34: 
   35: @cindex current working directory
   36: @cindex working directory
   37: @cindex change working directory
   38: Each process has associated with it a directory, called its @dfn{current
   39: working directory} or simply @dfn{working directory}, that is used in
   40: the resolution of relative file names (@pxref{File Name Resolution}).
   41: 
   42: When you log in and begin a new session, your working directory is
   43: initially set to the home directory associated with your login account
   44: in the system user database.  You can find any user's home directory
   45: using the @code{getpwuid} or @code{getpwnam} functions; see @ref{User
   46: Database}.
   47: 
   48: Users can change the working directory using shell commands like
   49: @code{cd}.  The functions described in this section are the primitives
   50: used by those commands and by other programs for examining and changing
   51: the working directory.
   52: @pindex cd
   53: 
   54: Prototypes for these functions are declared in the header file
   55: @file{unistd.h}.
   56: @pindex unistd.h
   57: 
   58: @comment unistd.h
   59: @comment POSIX.1
   60: @deftypefun {char *} getcwd (char *@var{buffer}, size_t @var{size})
   61: The @code{getcwd} function returns an absolute file name representing
   62: the current working directory, storing it in the character array
   63: @var{buffer} that you provide.  The @var{size} argument is how you tell
   64: the system the allocation size of @var{buffer}.
   65: 
   66: The GNU library version of this function also permits you to specify a
   67: null pointer for the @var{buffer} argument.  Then @code{getcwd}
   68: allocates a buffer automatically, as with @code{malloc}
   69: (@pxref{Unconstrained Allocation}).  If the @var{size} is greater than
   70: zero, then the buffer is that large; otherwise, the buffer is as large
   71: as necessary to hold the result.
   72: 
   73: The return value is @var{buffer} on success and a null pointer on failure.
   74: The following @code{errno} error conditions are defined for this function:
   75: 
   76: @table @code
   77: @item EINVAL
   78: The @var{size} argument is zero and @var{buffer} is not a null pointer.
   79: 
   80: @item ERANGE
   81: The @var{size} argument is less than the length of the working directory
   82: name.  You need to allocate a bigger array and try again.
   83: 
   84: @item EACCES
   85: Permission to read or search a component of the file name was denied.
   86: @end table
   87: @end deftypefun
   88: 
   89: You could implement the behavior of GNU's @w{@code{getcwd (NULL, 0)}}
   90: using only the standard behavior of @code{getcwd}:
   91: 
   92: @smallexample
   93: char *
   94: gnu_getcwd ()
   95: @{
   96:   size_t size = 100;
   97: 
   98:   while (1)
   99:     @{
  100:       char *buffer = (char *) xmalloc (size);
  101:       if (getcwd (buffer, size) == buffer)
  102:         return buffer;
  103:       free (buffer);
  104:       if (errno != ERANGE)
  105:         return 0;
  106:       size *= 2;
  107:     @}
  108: @}
  109: @end smallexample
  110: 
  111: @noindent
  112: @xref{Malloc Examples}, for information about @code{xmalloc}, which is
  113: not a library function but is a customary name used in most GNU
  114: software.
  115: 
  116: @comment unistd.h
  117: @comment BSD
  118: @deftypefn {Deprecated Function} {char *} getwd (char *@var{buffer})
  119: This is similar to @code{getcwd}, but has no way to specify the size of
  120: the buffer.  The GNU library provides @code{getwd} only
  121: for backwards compatibility with BSD.
  122: 
  123: The @var{buffer} argument should be a pointer to an array at least
  124: @code{PATH_MAX} bytes long (@pxref{Limits for Files}).  In the GNU
  125: system there is no limit to the size of a file name, so this is not
  126: necessarily enough space to contain the directory name.  That is why
  127: this function is deprecated.
  128: @end deftypefn
  129: 
  130: @comment unistd.h
  131: @comment GNU
  132: @deftypefun {char *} get_current_dir_name (void)
  133: @vindex PWD
  134: This @code{get_current_dir_name} function is basically equivalent to
  135: @w{@code{getcwd (NULL, 0)}}.  The only difference is that the value of
  136: the @code{PWD} variable is returned if this value is correct.  This is a
  137: subtle difference which is visible if the path described by the
  138: @code{PWD} value is using one or more symbol links in which case the
  139: value returned by @code{getcwd} can resolve the symbol links and
  140: therefore yield a different result.
  141: 
  142: This function is a GNU extension.
  143: @end deftypefun
  144: 
  145: @comment unistd.h
  146: @comment POSIX.1
  147: @deftypefun int chdir (const char *@var{filename})
  148: This function is used to set the process's working directory to
  149: @var{filename}.
  150: 
  151: The normal, successful return value from @code{chdir} is @code{0}.  A
  152: value of @code{-1} is returned to indicate an error.  The @code{errno}
  153: error conditions defined for this function are the usual file name
  154: syntax errors (@pxref{File Name Errors}), plus @code{ENOTDIR} if the
  155: file @var{filename} is not a directory.
  156: @end deftypefun
  157: 
  158: @comment unistd.h
  159: @comment XPG
  160: @deftypefun int fchdir (int @var{filedes})
  161: This function is used to set the process's working directory to
  162: directory associated with the file descriptor @var{filedes}.
  163: 
  164: The normal, successful return value from @code{fchdir} is @code{0}.  A
  165: value of @code{-1} is returned to indicate an error.  The following
  166: @code{errno} error conditions are defined for this function:
  167: 
  168: @table @code
  169: @item EACCES
  170: Read permission is denied for the directory named by @code{dirname}.
  171: 
  172: @item EBADF
  173: The @var{filedes} argument is not a valid file descriptor.
  174: 
  175: @item ENOTDIR
  176: The file descriptor @var{filedes} is not associated with a directory.
  177: 
  178: @item EINTR
  179: The function call was interrupt by a signal.
  180: 
  181: @item EIO
  182: An I/O error occurred.
  183: @end table
  184: @end deftypefun
  185: 
  186: 
  187: @node Accessing Directories
  188: @section Accessing Directories
  189: @cindex accessing directories
  190: @cindex reading from a directory
  191: @cindex directories, accessing
  192: 
  193: The facilities described in this section let you read the contents of a
  194: directory file.  This is useful if you want your program to list all the
  195: files in a directory, perhaps as part of a menu.
  196: 
  197: @cindex directory stream
  198: The @code{opendir} function opens a @dfn{directory stream} whose
  199: elements are directory entries.  Alternatively @code{fdopendir} can be
  200: used which can have advantages if the program needs to have more
  201: control over the way the directory is opened for reading.  This
  202: allows, for instance, to pass the @code{O_NOATIME} flag to
  203: @code{open}.
  204: 
  205: You use the @code{readdir} function on the directory stream to
  206: retrieve these entries, represented as @w{@code{struct dirent}}
  207: objects.  The name of the file for each entry is stored in the
  208: @code{d_name} member of this structure.  There are obvious parallels
  209: here to the stream facilities for ordinary files, described in
  210: @ref{I/O on Streams}.
  211: 
  212: @menu
  213: * Directory Entries::           Format of one directory entry.
  214: * Opening a Directory::         How to open a directory stream.
  215: * Reading/Closing Directory::   How to read directory entries from the stream.
  216: * Simple Directory Lister::     A very simple directory listing program.
  217: * Random Access Directory::     Rereading part of the directory
  218:                                  already read with the same stream.
  219: * Scanning Directory Content::  Get entries for user selected subset of
  220:                                  contents in given directory.
  221: * Simple Directory Lister Mark II::  Revised version of the program.
  222: @end menu
  223: 
  224: @node Directory Entries
  225: @subsection Format of a Directory Entry
  226: 
  227: @pindex dirent.h
  228: This section describes what you find in a single directory entry, as you
  229: might obtain it from a directory stream.  All the symbols are declared
  230: in the header file @file{dirent.h}.
  231: 
  232: @comment dirent.h
  233: @comment POSIX.1
  234: @deftp {Data Type} {struct dirent}
  235: This is a structure type used to return information about directory
  236: entries.  It contains the following fields:
  237: 
  238: @table @code
  239: @item char d_name[]
  240: This is the null-terminated file name component.  This is the only
  241: field you can count on in all POSIX systems.
  242: 
  243: @item ino_t d_fileno
  244: This is the file serial number.  For BSD compatibility, you can also
  245: refer to this member as @code{d_ino}.  In the GNU system and most POSIX
  246: systems, for most files this the same as the @code{st_ino} member that
  247: @code{stat} will return for the file.  @xref{File Attributes}.
  248: 
  249: @item unsigned char d_namlen
  250: This is the length of the file name, not including the terminating null
  251: character.  Its type is @code{unsigned char} because that is the integer
  252: type of the appropriate size
  253: 
  254: @item unsigned char d_type
  255: This is the type of the file, possibly unknown.  The following constants
  256: are defined for its value:
  257: 
  258: @vtable @code
  259: @item DT_UNKNOWN
  260: The type is unknown.  On some systems this is the only value returned.
  261: 
  262: @item DT_REG
  263: A regular file.
  264: 
  265: @item DT_DIR
  266: A directory.
  267: 
  268: @item DT_FIFO
  269: A named pipe, or FIFO.  @xref{FIFO Special Files}.
  270: 
  271: @item DT_SOCK
  272: A local-domain socket.  @c !!! @xref{Local Domain}.
  273: 
  274: @item DT_CHR
  275: A character device.
  276: 
  277: @item DT_BLK
  278: A block device.
  279: @end vtable
  280: 
  281: This member is a BSD extension.  The symbol @code{_DIRENT_HAVE_D_TYPE}
  282: is defined if this member is available.  On systems where it is used, it
  283: corresponds to the file type bits in the @code{st_mode} member of
  284: @code{struct statbuf}.  If the value cannot be determine the member
  285: value is DT_UNKNOWN.  These two macros convert between @code{d_type}
  286: values and @code{st_mode} values:
  287: 
  288: @comment dirent.h
  289: @comment BSD
  290: @deftypefun int IFTODT (mode_t @var{mode})
  291: This returns the @code{d_type} value corresponding to @var{mode}.
  292: @end deftypefun
  293: 
  294: @comment dirent.h
  295: @comment BSD
  296: @deftypefun mode_t DTTOIF (int @var{dtype})
  297: This returns the @code{st_mode} value corresponding to @var{dtype}.
  298: @end deftypefun
  299: @end table
  300: 
  301: This structure may contain additional members in the future.  Their
  302: availability is always announced in the compilation environment by a
  303: macro names @code{_DIRENT_HAVE_D_@var{xxx}} where @var{xxx} is replaced
  304: by the name of the new member.  For instance, the member @code{d_reclen}
  305: available on some systems is announced through the macro
  306: @code{_DIRENT_HAVE_D_RECLEN}.
  307: 
  308: When a file has multiple names, each name has its own directory entry.
  309: The only way you can tell that the directory entries belong to a
  310: single file is that they have the same value for the @code{d_fileno}
  311: field.
  312: 
  313: File attributes such as size, modification times etc., are part of the
  314: file itself, not of any particular directory entry.  @xref{File
  315: Attributes}.
  316: @end deftp
  317: 
  318: @node Opening a Directory
  319: @subsection Opening a Directory Stream
  320: 
  321: @pindex dirent.h
  322: This section describes how to open a directory stream.  All the symbols
  323: are declared in the header file @file{dirent.h}.
  324: 
  325: @comment dirent.h
  326: @comment POSIX.1
  327: @deftp {Data Type} DIR
  328: The @code{DIR} data type represents a directory stream.
  329: @end deftp
  330: 
  331: You shouldn't ever allocate objects of the @code{struct dirent} or
  332: @code{DIR} data types, since the directory access functions do that for
  333: you.  Instead, you refer to these objects using the pointers returned by
  334: the following functions.
  335: 
  336: @comment dirent.h
  337: @comment POSIX.1
  338: @deftypefun {DIR *} opendir (const char *@var{dirname})
  339: The @code{opendir} function opens and returns a directory stream for
  340: reading the directory whose file name is @var{dirname}.  The stream has
  341: type @code{DIR *}.
  342: 
  343: If unsuccessful, @code{opendir} returns a null pointer.  In addition to
  344: the usual file name errors (@pxref{File Name Errors}), the
  345: following @code{errno} error conditions are defined for this function:
  346: 
  347: @table @code
  348: @item EACCES
  349: Read permission is denied for the directory named by @code{dirname}.
  350: 
  351: @item EMFILE
  352: The process has too many files open.
  353: 
  354: @item ENFILE
  355: The entire system, or perhaps the file system which contains the
  356: directory, cannot support any additional open files at the moment.
  357: (This problem cannot happen on the GNU system.)
  358: 
  359: @item ENOMEM
  360: Not enough memory available.
  361: @end table
  362: 
  363: The @code{DIR} type is typically implemented using a file descriptor,
  364: and the @code{opendir} function in terms of the @code{open} function.
  365: @xref{Low-Level I/O}.  Directory streams and the underlying
  366: file descriptors are closed on @code{exec} (@pxref{Executing a File}).
  367: @end deftypefun
  368: 
  369: The directory which is opened for reading by @code{opendir} is
  370: identified by the name.  In some situations this is not sufficient.
  371: Or the way @code{opendir} implicitly creates a file descriptor for the
  372: directory is not the way a program might want it.  In these cases an
  373: alternative interface can be used.
  374: 
  375: @comment dirent.h
  376: @comment GNU
  377: @deftypefun {DIR *} fdopendir (int @var{fd})
  378: The @code{fdopendir} function works just like @code{opendir} but
  379: instead of taking a file name and opening a file descriptor for the
  380: directory the caller is required to provide a file descriptor.  This
  381: file descriptor is then used in subsequent uses of the returned
  382: directory stream object.
  383: 
  384: The caller must make sure the file descriptor is associated with a
  385: directory and it allows reading.
  386: 
  387: If the @code{fdopendir} call returns successfully the file descriptor
  388: is now under the control of the system.  It can be used in the same
  389: way the descriptor implicitly created by @code{opendir} can be used
  390: but the program must not close the descriptor.
  391: 
  392: In case the function is unsuccessful it returns a null pointer and the
  393: file descriptor remains to be usable by the program.  The following
  394: @code{errno} error conditions are defined for this function:
  395: 
  396: @table @code
  397: @item EBADF
  398: The file descriptor is not valid.
  399: 
  400: @item ENOTDIR
  401: The file descriptor is not associated with a directory.
  402: 
  403: @item EINVAL
  404: The descriptor does not allow reading the directory content.
  405: 
  406: @item ENOMEM
  407: Not enough memory available.
  408: @end table
  409: @end deftypefun
  410: 
  411: In some situations it can be desirable to get hold of the file
  412: descriptor which is created by the @code{opendir} call.  For instance,
  413: to switch the current working directory to the directory just read the
  414: @code{fchdir} function could be used.  Historically the @code{DIR} type
  415: was exposed and programs could access the fields.  This does not happen
  416: in the GNU C library.  Instead a separate function is provided to allow
  417: access.
  418: 
  419: @comment dirent.h
  420: @comment GNU
  421: @deftypefun int dirfd (DIR *@var{dirstream})
  422: The function @code{dirfd} returns the file descriptor associated with
  423: the directory stream @var{dirstream}.  This descriptor can be used until
  424: the directory is closed with @code{closedir}.  If the directory stream
  425: implementation is not using file descriptors the return value is
  426: @code{-1}.
  427: @end deftypefun
  428: 
  429: @node Reading/Closing Directory
  430: @subsection Reading and Closing a Directory Stream
  431: 
  432: @pindex dirent.h
  433: This section describes how to read directory entries from a directory
  434: stream, and how to close the stream when you are done with it.  All the
  435: symbols are declared in the header file @file{dirent.h}.
  436: 
  437: @comment dirent.h
  438: @comment POSIX.1
  439: @deftypefun {struct dirent *} readdir (DIR *@var{dirstream})
  440: This function reads the next entry from the directory.  It normally
  441: returns a pointer to a structure containing information about the file.
  442: This structure is statically allocated and can be rewritten by a
  443: subsequent call.
  444: 
  445: @strong{Portability Note:} On some systems @code{readdir} may not
  446: return entries for @file{.} and @file{..}, even though these are always
  447: valid file names in any directory.  @xref{File Name Resolution}.
  448: 
  449: If there are no more entries in the directory or an error is detected,
  450: @code{readdir} returns a null pointer.  The following @code{errno} error
  451: conditions are defined for this function:
  452: 
  453: @table @code
  454: @item EBADF
  455: The @var{dirstream} argument is not valid.
  456: @end table
  457: 
  458: @code{readdir} is not thread safe.  Multiple threads using
  459: @code{readdir} on the same @var{dirstream} may overwrite the return
  460: value.  Use @code{readdir_r} when this is critical.
  461: @end deftypefun
  462: 
  463: @comment dirent.h
  464: @comment GNU
  465: @deftypefun int readdir_r (DIR *@var{dirstream}, struct dirent *@var{entry}, struct dirent **@var{result})
  466: This function is the reentrant version of @code{readdir}.  Like
  467: @code{readdir} it returns the next entry from the directory.  But to
  468: prevent conflicts between simultaneously running threads the result is
  469: not stored in statically allocated memory.  Instead the argument
  470: @var{entry} points to a place to store the result.
  471: 
  472: Normally @code{readdir_r} returns zero and sets @code{*@var{result}}
  473: to @var{entry}.  If there are no more entries in the directory or an
  474: error is detected, @code{readdir_r} sets @code{*@var{result}} to a
  475: null pointer and returns a nonzero error code, also stored in
  476: @code{errno}, as described for @code{readdir}.
  477: 
  478: @strong{Portability Note:} On some systems @code{readdir_r} may not
  479: return a NUL terminated string for the file name, even when there is no
  480: @code{d_reclen} field in @code{struct dirent} and the file
  481: name is the maximum allowed size.  Modern systems all have the
  482: @code{d_reclen} field, and on old systems multi-threading is not
  483: critical.  In any case there is no such problem with the @code{readdir}
  484: function, so that even on systems without the @code{d_reclen} member one
  485: could use multiple threads by using external locking.
  486: 
  487: It is also important to look at the definition of the @code{struct
  488: dirent} type.  Simply passing a pointer to an object of this type for
  489: the second parameter of @code{readdir_r} might not be enough.  Some
  490: systems don't define the @code{d_name} element sufficiently long.  In
  491: this case the user has to provide additional space.  There must be room
  492: for at least @code{NAME_MAX + 1} characters in the @code{d_name} array.
  493: Code to call @code{readdir_r} could look like this:
  494: 
  495: @smallexample
  496:   union
  497:   @{
  498:     struct dirent d;
  499:     char b[offsetof (struct dirent, d_name) + NAME_MAX + 1];
  500:   @} u;
  501: 
  502:   if (readdir_r (dir, &u.d, &res) == 0)
  503:     @dots{}
  504: @end smallexample
  505: @end deftypefun
  506: 
  507: To support large filesystems on 32-bit machines there are LFS variants
  508: of the last two functions.
  509: 
  510: @comment dirent.h
  511: @comment LFS
  512: @deftypefun {struct dirent64 *} readdir64 (DIR *@var{dirstream})
  513: The @code{readdir64} function is just like the @code{readdir} function
  514: except that it returns a pointer to a record of type @code{struct
  515: dirent64}.  Some of the members of this data type (notably @code{d_ino})
  516: might have a different size to allow large filesystems.
  517: 
  518: In all other aspects this function is equivalent to @code{readdir}.
  519: @end deftypefun
  520: 
  521: @comment dirent.h
  522: @comment LFS
  523: @deftypefun int readdir64_r (DIR *@var{dirstream}, struct dirent64 *@var{entry}, struct dirent64 **@var{result})
  524: The @code{readdir64_r} function is equivalent to the @code{readdir_r}
  525: function except that it takes parameters of base type @code{struct
  526: dirent64} instead of @code{struct dirent} in the second and third
  527: position.  The same precautions mentioned in the documentation of
  528: @code{readdir_r} also apply here.
  529: @end deftypefun
  530: 
  531: @comment dirent.h
  532: @comment POSIX.1
  533: @deftypefun int closedir (DIR *@var{dirstream})
  534: This function closes the directory stream @var{dirstream}.  It returns
  535: @code{0} on success and @code{-1} on failure.
  536: 
  537: The following @code{errno} error conditions are defined for this
  538: function:
  539: 
  540: @table @code
  541: @item EBADF
  542: The @var{dirstream} argument is not valid.
  543: @end table
  544: @end deftypefun
  545: 
  546: @node Simple Directory Lister
  547: @subsection Simple Program to List a Directory
  548: 
  549: Here's a simple program that prints the names of the files in
  550: the current working directory:
  551: 
  552: @smallexample
  553: @include dir.c.texi
  554: @end smallexample
  555: 
  556: The order in which files appear in a directory tends to be fairly
  557: random.  A more useful program would sort the entries (perhaps by
  558: alphabetizing them) before printing them; see
  559: @ref{Scanning Directory Content}, and @ref{Array Sort Function}.
  560: 
  561: 
  562: @node Random Access Directory
  563: @subsection Random Access in a Directory Stream
  564: 
  565: @pindex dirent.h
  566: This section describes how to reread parts of a directory that you have
  567: already read from an open directory stream.  All the symbols are
  568: declared in the header file @file{dirent.h}.
  569: 
  570: @comment dirent.h
  571: @comment POSIX.1
  572: @deftypefun void rewinddir (DIR *@var{dirstream})
  573: The @code{rewinddir} function is used to reinitialize the directory
  574: stream @var{dirstream}, so that if you call @code{readdir} it
  575: returns information about the first entry in the directory again.  This
  576: function also notices if files have been added or removed to the
  577: directory since it was opened with @code{opendir}.  (Entries for these
  578: files might or might not be returned by @code{readdir} if they were
  579: added or removed since you last called @code{opendir} or
  580: @code{rewinddir}.)
  581: @end deftypefun
  582: 
  583: @comment dirent.h
  584: @comment BSD
  585: @deftypefun long int telldir (DIR *@var{dirstream})
  586: The @code{telldir} function returns the file position of the directory
  587: stream @var{dirstream}.  You can use this value with @code{seekdir} to
  588: restore the directory stream to that position.
  589: @end deftypefun
  590: 
  591: @comment dirent.h
  592: @comment BSD
  593: @deftypefun void seekdir (DIR *@var{dirstream}, long int @var{pos})
  594: The @code{seekdir} function sets the file position of the directory
  595: stream @var{dirstream} to @var{pos}.  The value @var{pos} must be the
  596: result of a previous call to @code{telldir} on this particular stream;
  597: closing and reopening the directory can invalidate values returned by
  598: @code{telldir}.
  599: @end deftypefun
  600: 
  601: 
  602: @node Scanning Directory Content
  603: @subsection Scanning the Content of a Directory
  604: 
  605: A higher-level interface to the directory handling functions is the
  606: @code{scandir} function.  With its help one can select a subset of the
  607: entries in a directory, possibly sort them and get a list of names as
  608: the result.
  609: 
  610: @comment dirent.h
  611: @comment BSD/SVID
  612: @deftypefun int scandir (const char *@var{dir}, struct dirent ***@var{namelist}, int (*@var{selector}) (const struct dirent *), int (*@var{cmp}) (const void *, const void *))
  613: 
  614: The @code{scandir} function scans the contents of the directory selected
  615: by @var{dir}.  The result in *@var{namelist} is an array of pointers to
  616: structure of type @code{struct dirent} which describe all selected
  617: directory entries and which is allocated using @code{malloc}.  Instead
  618: of always getting all directory entries returned, the user supplied
  619: function @var{selector} can be used to decide which entries are in the
  620: result.  Only the entries for which @var{selector} returns a non-zero
  621: value are selected.
  622: 
  623: Finally the entries in *@var{namelist} are sorted using the
  624: user-supplied function @var{cmp}.  The arguments passed to the @var{cmp}
  625: function are of type @code{struct dirent **}, therefore one cannot
  626: directly use the @code{strcmp} or @code{strcoll} functions; instead see
  627: the functions @code{alphasort} and @code{versionsort} below.
  628: 
  629: The return value of the function is the number of entries placed in
  630: *@var{namelist}.  If it is @code{-1} an error occurred (either the
  631: directory could not be opened for reading or the malloc call failed) and
  632: the global variable @code{errno} contains more information on the error.
  633: @end deftypefun
  634: 
  635: As described above the fourth argument to the @code{scandir} function
  636: must be a pointer to a sorting function.  For the convenience of the
  637: programmer the GNU C library contains implementations of functions which
  638: are very helpful for this purpose.
  639: 
  640: @comment dirent.h
  641: @comment BSD/SVID
  642: @deftypefun int alphasort (const void *@var{a}, const void *@var{b})
  643: The @code{alphasort} function behaves like the @code{strcoll} function
  644: (@pxref{String/Array Comparison}).  The difference is that the arguments
  645: are not string pointers but instead they are of type
  646: @code{struct dirent **}.
  647: 
  648: The return value of @code{alphasort} is less than, equal to, or greater
  649: than zero depending on the order of the two entries @var{a} and @var{b}.
  650: @end deftypefun
  651: 
  652: @comment dirent.h
  653: @comment GNU
  654: @deftypefun int versionsort (const void *@var{a}, const void *@var{b})
  655: The @code{versionsort} function is like @code{alphasort} except that it
  656: uses the @code{strverscmp} function internally.
  657: @end deftypefun
  658: 
  659: If the filesystem supports large files we cannot use the @code{scandir}
  660: anymore since the @code{dirent} structure might not able to contain all
  661: the information.  The LFS provides the new type @w{@code{struct
  662: dirent64}}.  To use this we need a new function.
  663: 
  664: @comment dirent.h
  665: @comment GNU
  666: @deftypefun int scandir64 (const char *@var{dir}, struct dirent64 ***@var{namelist}, int (*@var{selector}) (const struct dirent64 *), int (*@var{cmp}) (const void *, const void *))
  667: The @code{scandir64} function works like the @code{scandir} function
  668: except that the directory entries it returns are described by elements
  669: of type @w{@code{struct dirent64}}.  The function pointed to by
  670: @var{selector} is again used to select the desired entries, except that
  671: @var{selector} now must point to a function which takes a
  672: @w{@code{struct dirent64 *}} parameter.
  673: 
  674: Similarly the @var{cmp} function should expect its two arguments to be
  675: of type @code{struct dirent64 **}.
  676: @end deftypefun
  677: 
  678: As @var{cmp} is now a function of a different type, the functions
  679: @code{alphasort} and @code{versionsort} cannot be supplied for that
  680: argument.  Instead we provide the two replacement functions below.
  681: 
  682: @comment dirent.h
  683: @comment GNU
  684: @deftypefun int alphasort64 (const void *@var{a}, const void *@var{b})
  685: The @code{alphasort64} function behaves like the @code{strcoll} function
  686: (@pxref{String/Array Comparison}).  The difference is that the arguments
  687: are not string pointers but instead they are of type
  688: @code{struct dirent64 **}.
  689: 
  690: Return value of @code{alphasort64} is less than, equal to, or greater
  691: than zero depending on the order of the two entries @var{a} and @var{b}.
  692: @end deftypefun
  693: 
  694: @comment dirent.h
  695: @comment GNU
  696: @deftypefun int versionsort64 (const void *@var{a}, const void *@var{b})
  697: The @code{versionsort64} function is like @code{alphasort64}, excepted that it
  698: uses the @code{strverscmp} function internally.
  699: @end deftypefun
  700: 
  701: It is important not to mix the use of @code{scandir} and the 64-bit
  702: comparison functions or vice versa.  There are systems on which this
  703: works but on others it will fail miserably.
  704: 
  705: @node Simple Directory Lister Mark II
  706: @subsection Simple Program to List a Directory, Mark II
  707: 
  708: Here is a revised version of the directory lister found above
  709: (@pxref{Simple Directory Lister}).  Using the @code{scandir} function we
  710: can avoid the functions which work directly with the directory contents.
  711: After the call the returned entries are available for direct use.
  712: 
  713: @smallexample
  714: @include dir2.c.texi
  715: @end smallexample
  716: 
  717: Note the simple selector function in this example.  Since we want to see
  718: all directory entries we always return @code{1}.
  719: 
  720: 
  721: @node Working with Directory Trees
  722: @section Working with Directory Trees
  723: @cindex directory hierarchy
  724: @cindex hierarchy, directory
  725: @cindex tree, directory
  726: 
  727: The functions described so far for handling the files in a directory
  728: have allowed you to either retrieve the information bit by bit, or to
  729: process all the files as a group (see @code{scandir}).  Sometimes it is
  730: useful to process whole hierarchies of directories and their contained
  731: files.  The X/Open specification defines two functions to do this.  The
  732: simpler form is derived from an early definition in @w{System V} systems
  733: and therefore this function is available on SVID-derived systems.  The
  734: prototypes and required definitions can be found in the @file{ftw.h}
  735: header.
  736: 
  737: There are four functions in this family: @code{ftw}, @code{nftw} and
  738: their 64-bit counterparts @code{ftw64} and @code{nftw64}.  These
  739: functions take as one of their arguments a pointer to a callback
  740: function of the appropriate type.
  741: 
  742: @comment ftw.h
  743: @comment GNU
  744: @deftp {Data Type} __ftw_func_t
  745: 
  746: @smallexample
  747: int (*) (const char *, const struct stat *, int)
  748: @end smallexample
  749: 
  750: The type of callback functions given to the @code{ftw} function.  The
  751: first parameter points to the file name, the second parameter to an
  752: object of type @code{struct stat} which is filled in for the file named
  753: in the first parameter.