Scanning Directory Content (The GNU C Library)

#### 14.3.6 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 struct dirent **, const struct dirent **))` ¶

  Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | See POSIX Safety Concepts.

  The `scandir` function scans the contents of the directory selected by dir. The result in *namelist is an array of pointers to structures 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 memory allocation 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 struct dirent **a, const struct dirent **b)` ¶

  Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | See POSIX Safety Concepts.

  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 struct dirent **a, const struct dirent **b)` ¶

  Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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 struct dirent64 **, const struct dirent64 **))` ¶

  Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | See POSIX Safety Concepts.

  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 struct dirent64 **a, const struct dirent **b)` ¶

  Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | See POSIX Safety Concepts.

  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 struct dirent64 **a, const struct dirent64 **b)` ¶

  Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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.