SCANDIR(3)             FreeBSD Library Functions Manual             SCANDIR(3)

NAME

     scandir, fdscandir, scandirat, scandir_b, fdscandir_b, fdscandirat_b,
     alphasort, versionsort - scan a directory

LIBRARY

     Standard C Library (libc, -lc)

SYNOPSIS

     #include <dirent.h>

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

     int
     fdscandir(int dirfd, struct dirent ***namelist,
         int (*select)(const struct dirent *),
         int (*compar)(const struct dirent **, const struct dirent **));

     int
     scandirat(int dirfd, const char *dirname, struct dirent ***namelist,
         int (*select)(const struct dirent *),
         int (*compar)(const struct dirent **, const struct dirent **));

     int
     scandir_b(const char *dirname, struct dirent ***namelist,
         int (^select)(const struct dirent *),
         int (^compar)(const struct dirent **, const struct dirent **));

     int
     fdscandir_b(int dirfd, struct dirent ***namelist,
         int (^select)(const struct dirent *),
         int (^compar)(const struct dirent **, const struct dirent **));

     int
     scandirat_b(int dirfd, 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);

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

DESCRIPTION

     The scandir() function reads the directory dirname and builds an array of
     pointers to directory entries using malloc(3).  It returns the number of
     entries in the array.  A pointer to the array of directory entries is
     stored in the location referenced by namelist (even if no entries were
     selected).

     The select argument 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 argument is a pointer to a user supplied subroutine which is
     passed to qsort(3) to sort the completed array.  If this pointer is null,
     the array is not sorted.

     The alphasort() function is a routine which can be used for the compar
     argument to sort the array alphabetically using strcoll(3).

     The versionsort() function is a routine which can be used for the compar
     argument to sort the array naturally using strverscmp(3).

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

     The fdscandir() function is similar to scandir(), but takes a file
     descriptor referencing a directory instead of a path.  The file
     descriptor is left open on return, regardless of outcome.

     The scandirat() function is similar to scandir(), but takes an additional
     dirfd argument.  If the supplied dirname is absolute, the function's
     behavior is identical to that of scandir(), the dirfd argument is unused.
     If dirname is relative, dirfd must be a valid file descriptor referencing
     a directory, in which case the dirname lookup is performed relative to
     the directory referenced by dirfd.  If dirfd has the special value
     AT_FDCWD, then the current process directory is used as the base for
     relative lookups.  See openat(2) for additional details.

     The scandir_b(), fdscandir_b(), and scandirat_b() functions behave in the
     same way as scandir(), fdscandir(), and scandirat(), respectively, but
     take blocks as arguments instead of function pointers and call qsort_b()
     rather than qsort().

DIAGNOSTICS

     The scandir(), fdscandir(), scandirat(), scandir_b(), fdscandir_b(), and
     scandirat_b() functions return the number of directory entries found on
     succes.  If the directory cannot be opened for reading, an error occurs
     while reading the directory, or malloc(3) cannot allocate enough memory
     to hold all the directory entries, they return -1 and set errno to an
     appropriate value.

ERRORS

     The scandir(), scandirat(), scandir_b(), and scandirat_b() functions may
     fail and set errno for any of the errors specified for the opendir(3),
     malloc(3), readdir(3), and closedir(3) functions.

     The fdscandir() and fdscandir_b() functions may fail and set errno for
     any of the errors specified for the fdopendir(3), malloc(3), readdir(3),
     and closedir(3) functions.

SEE ALSO

     openat(2), directory(3), malloc(3), qsort(3), strcoll(3), strverscmp(3),
     dir(5)

STANDARDS

     The alphasort() and scandir() functions are expected to conform to IEEE
     Std 1003.1-2008 ("POSIX.1").  The scandirat() and versionsort() functions
     are GNU extensions and conform to no standard.  The fdscandir(),
     scandir_b(), fdscandir_b(), and scandirat_b() functions are FreeBSD
     extensions.

HISTORY

     The scandir() and alphasort() functions appeared in 4.2BSD.  The
     scandir_b() function was added in FreeBSD 11.0.  The scandirat() and
     versionsort() functions were added in FreeBSD 13.2.  The fdscandir(),
     fdscandir_b(), and scandirat_b() functions were added in FreeBSD 15.0.

FreeBSD 15.1-STABLE-HBSD         June 25, 2025                      SCANDIR(3)