scandir(3C)scandir(3C)NAMEscandir(), alphasort() - scan a directory
SYNOPSISDESCRIPTION
reads the directory dirname and builds an array of pointers to direc‐
tory entries using (see malloc(3C)). It returns the number of entries
in the array and a pointer to the array through namelist.
The select parameter is a pointer to a user-supplied subroutine which
is called by to select which entries are to be included in the array.
The select routine is passed a pointer to a directory entry and should
return a non-zero value if the directory entry is to be included in the
array. If select is null, then all the directory entries will be
included.
The compar parameter is a pointer to a user-supplied subroutine which
is passed to qsort(3C) to sort the completed array. If this pointer is
null, the array is not sorted. is a routine which can be used for the
compar parameter to sort the array alphabetically.
EXTERNAL INFLUENCES
Locale
The category determines the collation ordering used by
The category determines the interpretation of bytes in the file name
portion of directory entries as single- and/or multi-byte characters by
the function.
Results are undefined if the locales specified by the and categories
use different code sets.
International Code Set Support
Single- and multi-byte character code sets are supported for
RETURN VALUE
If successful, returns the number of directory entries selected, and
through the namelist parameter returns a pointer to the array. returns
−1, if the directory cannot be opened for reading or cannot allocate
enough memory to hold all the data structures.
APPLICATION USAGE
uses to allocate memory for the array associated with the namelist
pointer. If the return value of is greater than or equal to zero (0),
memory allocated for the namelist pointer needs to be freed by the
application using (see malloc(3C)) by first freeing each pointer in the
array followed by the array itself.
EXAMPLES
The example program below scans the directory. It does not exclude any
entries since select is NULL. The contents of are sorted by It prints
out how many entries are in and the sorted entries of the directory.
The memory used by is returned using
#include <sys/types.h>
#include <stdio.h>
#include <dirent.h>
extern int scandir();
extern int alphasort();
main()
{
int num_entries, i;
struct dirent **namelist, **list;
if ((num_entries =
scandir("/tmp", &namelist, NULL, alphasort)) < 0) {
fprintf(stderr, "Unexpected error\n");
exit(1);
}
printf("Number of entries is %d\n", num_entries);
if (num_entries) {
printf("Entries are:");
for (i=0, list=namelist; i<num_entries; i++) {
printf(" %s", (*list)−>d_name);
free(*list);
list++;
}
}
free(namelist);
printf("\n");
exit(0);
}
WARNINGS
For 32-bit applications, the d_ino field of the struct returned by or
may overflow for filesystems that use 64-bit values. In this case the
most-significant bytes will be truncated without generating an error
and d_ino values may not be unique.
SEE ALSOdirectory(3C), malloc(3C), qsort(3C), string(3C), dirent(5),
thread_safety(5).
scandir(3C)