Next: Simple Directory Lister Mark II, Previous: Random Access Directory, Up: Accessing Directories
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.
The
scandirfunction scans the contents of the directory selected by dir. The result in *namelist is an array of pointers to structure of typestruct direntwhich describe all selected directory entries and which is allocated usingmalloc. 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 thestrcmporstrcollfunctions; instead see the functionsalphasortandversionsortbelow.The return value of the function is the number of entries placed in *namelist. If it is
-1an error occurred (either the directory could not be opened for reading or the malloc call failed) and the global variableerrnocontains 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.
The
alphasortfunction behaves like thestrcollfunction (see String/Array Comparison). The difference is that the arguments are not string pointers but instead they are of typestruct dirent **.The return value of
alphasortis less than, equal to, or greater than zero depending on the order of the two entries a and b.
The
versionsortfunction is likealphasortexcept that it uses thestrverscmpfunction 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.
The
scandir64function works like thescandirfunction except that the directory entries it returns are described by elements of typestruct 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 astruct 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.
The
alphasort64function behaves like thestrcollfunction (see String/Array Comparison). The difference is that the arguments are not string pointers but instead they are of typestruct dirent64 **.Return value of
alphasort64is less than, equal to, or greater than zero depending on the order of the two entries a and b.
The
versionsort64function is likealphasort64, excepted that it uses thestrverscmpfunction 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.