Scans or sorts directory contents.
Standard C Library (libc.a)
#include <sys/types.h>
#include <sys/dir.h>int scandir(DirectoryName,NameList,Select,Compare)
char * DirectoryName;
struct dirent * (* NameList [ ]);
int (* Select) (struct dirent *);
int (* Compare)(void *, void *);
int alphasort ( Directory1,Directory2)
void *Directory1, *Directory2;
int scandir64(DirectoryName,NameList,Select,Compare)
char * DirectoryName;
struct dirent64 * (* NameList [ ]);
int (* Select) (struct dirent64 *);
int (* Compare)(void *, void *);
int alphasort64 ( Directory1,Directory2)
void *Directory1, *Directory2;
The scandir subroutine reads the directory pointed to by the DirectoryName parameter, and then uses the malloc subroutine to create an array of pointers to directory entries. The scandir subroutine returns the number of entries in the array and, through the NameList parameter, a pointer to the array.
The Select parameter points to a user-supplied subroutine that is called by the scandir subroutine to select which entries to include in the array. The selection routine is passed a pointer to a directory entry and should return a nonzero value for a directory entry that is included in the array. If the Select parameter is a null value, all directory entries are included.
The Compare parameter points to a user-supplied subroutine. This routine is passed to the qsort subroutine to sort the completed array. If the Compare parameter is a null value, the array is not sorted. The alphasort subroutine provides comparison functions for sorting alphabetically.
The memory allocated to the array can be deallocated by freeing each pointer in the array, and the array itself, with the free subroutine.
The alphasort subroutine treats Directory1 and Directory2 as pointers to dirent pointers and alphabetically compares them. This subroutine can be passed as the Compare parameter to either the scandir subroutine or the qsort subroutine, or a user-supplied subroutine can be used.
The scandir64 subroutine is similar to the scandir subroutine except that it returns a pointer to a list of pointers to struct dirent64 rather than of struct dirent.
The alphasort64 subroutine treats Directory1 and Directory2 as pointers to dirent64 pointers and alphabetically compares them. This subroutine can be passed as the Compare parameter to the scandir64 subroutine, or a user-supplied subroutine can be used.
| Item | Description |
|---|---|
| DirectoryName | Points to the directory name. |
| NameList | Points to the array of pointers to directory entries. |
| Select | Points to a user-supplied subroutine that is called by the scandir subroutine to select which entries to include in the array. |
| Compare | Points to a user-supplied subroutine that sorts the completed array. |
| Directory1, Directory2 | Point to dirent structures for alphasort, or to dirent64 structures for alphasort64. |
The scandir subroutine returns the value -1 if the directory cannot be opened for reading or if the malloc subroutine cannot allocate enough memory to hold all the data structures. If successful, the scandir subroutine returns the number of entries found.
The alphasort subroutine returns the following values:
| Item | Description |
|---|---|
| Less than 0 | The dirent structure pointed to by the Directory1 parameter is lexically less than the dirent structure pointed to by the Directory2 parameter. |
| 0 | The dirent structures pointed to by the Directory1 parameter and the Directory2 parameter are equal. |
| Greater than 0 | The dirent structure pointed to by the Directory1 parameter is lexically greater than the dirent structure pointed to by the Directory2 parameter. |
The scandir64 and alphasort64 subroutines return the similar values as scandir and alphasort subroutines, except that returned pointers associated with a dirent structure are now associated with a dirent64 structure.