SCANDIR(3) — UNIX Programmer’s Manual

NAME

scandir, alphasort − scan a directory

SYNOPSIS

#include <sys/types.h>
#include <sys/dir.h>
extern int scandir();
extern int alphasort();

scandir(dirname, namelist, select, compare)
char ∗dirname;
struct direct ∗∗∗namelist;
int (∗select)();
int (∗compare)();

alphasort(d1, d2)
struct direct ∗∗d1, ∗∗d2;

DESCRIPTION

Scandir reads the directory dirname and builds an array of pointers to directory entries using malloc(3). Scandir fills in the pointer namelist so that it points to the first element of the array, and returns the number of entries in the array. You must define a pointer to pointer to struct direct and pass the address to scandir for this to work.

The select parameter is a pointer to a user supplied function 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 (see /usr/include/sys/dir.h) and should return a non-zero value if the directory entry is to be included in the array. If select is the null function pointer ((int (∗)())0), then all the directory entries will be included.

The compare parameter is a pointer to a user supplied function which is passed to qsort(3) to sort the completed array. If this pointer is the null function pointer ((int (∗)()0), the array is not sorted. Alphasort is a routine which can be used for the compare parameter to sort the array alphabetically.

The memory allocated for the array can be deallocated with free (see malloc(3)) by freeing each pointer in the array and the array itself.

DIAGNOSTICS

Scandir returns −1 if the directory cannot be opened for reading or if malloc(3) cannot allocate enough memory to hold all the data structures.

EXAMPLES

The following program takes a single argument and lists all files in the current directory (in alphabetical order) that are prefixed with the given argument. If you give it the empty string e.g. "", it will list all the files in the current directory.

#include <sys/types.h>
#include <sys/dir.h>
#include <stdio.h>
extern int scandir(), alphasort();
static char ∗pcPrefix;     /∗ select only files with this prefix   ∗/
/∗
∗ select only files that begin with the prefix specified by pcPrefix
∗/
static int
SelectFiles(pSD)
        struct direct ∗pSD;
{
        return 0 == strncmp(pcPrefix, pSD->d_name, strlen(pcPrefix));
}
int
main(argc, argv)
        int argc;
        char ∗∗argv;
{
        register int i;
        auto struct direct ∗∗ppSD;
        static char acFileName[] = ".";
        int iCount;
         if (2 != argc) {
                fprintf(stderr, "Usage: %s fileprefix\n", argv[0]);
                exit(1);
        }
        pcPrefix = argv[1];
        if (-1 == (iCount = scandir(acFileName, & ppSD, SelectFiles, alphasort))) {
                perror(acFileName);
                exit(2);
        }
        for (i = 0; i < iCount; ++i) { /∗ print and free each entry    ∗/
                printf("%s\n", ppSD[i]->d_name);
                free((char ∗)ppSD[i]);
        }
        free((char ∗)ppSD);             /∗ free the array               ∗/
        exit(0);
}

Museum