GNU Info

(libc.info)Scanning Directory Content

---

Next: Simple Directory Lister Mark II Prev: Random Access Directory Up: Accessing Directories

---

Enter node , (file) or (file)node

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
     (Note: 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
     (Note: 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.