scandir(3C)

NAME

scandir(), alphasort() — scan a directory

SYNOPSIS

#include <dirent.h> 

extern int scandir( 
    const char *dirname, 
    struct dirent ***namelist, 
    int (*select) (const struct dirent *), 
    int (*compar) (const struct dirent **, 
             const struct dirent ** 
    ) 
); 

int alphasort( 
     const struct dirent **d1, 
     const struct dirent **d2 
); 

DESCRIPTION

scandir() reads the directory dirname and builds an array of pointers to directory entries using malloc() (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 scandir() 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. alphasort() is a routine which can be used for the compar parameter to sort the array alphabetically.

EXTERNAL INFLUENCES

Locale

The LC_COLLATE category determines the collation ordering used by alphasort().

The LC_CTYPE category determines the interpretation of bytes in the file name portion of directory entries as single- and/or multi-byte characters by the alphasort() function.

Results are undefined if the locales specified by the LC_COLLATE and LC_CTYPE categories use different code sets.

International Code Set Support

Single- and multi-byte character code sets are supported for alphasort().

RETURN VALUE

If successful, scandir() returns the number of directory entries selected, and through the namelist parameter returns a pointer to the array. scandir() returns -1, if the directory cannot be opened for reading or cannot allocate enough memory to hold all the data structures.

APPLICATION USAGE

scandir() uses malloc() to allocate memory for the array associated with the namelist pointer. If the return value of scandir() is greater than or equal to zero (0), memory allocated for the namelist pointer needs to be freed by the application using free() (see malloc(3C)) by first freeing each pointer in the array followed by the array itself.

EXAMPLES

The example program below scans the /tmp directory. It does not exclude any entries since select is NULL. The contents of namelist are sorted by alphasort(). It prints out how many entries are in /tmp and the sorted entries of the /tmp directory. The memory used by scandir() is returned using free().

#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 dirent struct returned by scandir() or alphasort() 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.