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