---
name: "alphasort"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/alphasort"
---

# alphasort(3)

scan a directory

## 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 \*selectconst struct dirent \**, *int \*comparconst struct dirent \*\*, const struct dirent \*\**);

*int*\

**fdscandir**(*int dirfd*, *struct dirent \*\*\*namelist*, *int \*selectconst struct dirent \**, *int \*comparconst struct dirent \*\*, const struct dirent \*\**);

*int*\

**scandirat**(*int dirfd*, *const char \*dirname*, *struct dirent \*\*\*namelist*, *int \*selectconst struct dirent \**, *int \*comparconst struct dirent \*\*, const struct dirent \*\**);

*int*\

**scandir\_b**(*const char \*dirname*, *struct dirent \*\*\*namelist*, *int ^selectconst struct dirent \**, *int ^comparconst struct dirent \*\*, const struct dirent \*\**);

*int*\

**fdscandir\_b**(*int dirfd*, *struct dirent \*\*\*namelist*, *int ^selectconst struct dirent \**, *int ^comparconst struct dirent \*\*, const struct dirent \*\**);

*int*\

**scandirat\_b**(*int dirfd*, *const char \*dirname*, *struct dirent \*\*\*namelist*, *int ^selectconst struct dirent \**, *int ^comparconst 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)](/malloc/3.md). 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)](/qsort/3.md) 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)](/strcoll/3.md).

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

The memory allocated for the array can be deallocated with [free(3)](/free/3.md), 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)](/openat/2.md) 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)](/malloc/3.md) 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)](/opendir/3.md), [malloc(3)](/malloc/3.md), [readdir(3)](/readdir/3.md), and [closedir(3)](/closedir/3.md) functions.

The **fdscandir**() and **fdscandir\_b**() functions may fail and set *errno* for any of the errors specified for the [fdopendir(3)](/fdopendir/3.md), [malloc(3)](/malloc/3.md), [readdir(3)](/readdir/3.md), and [closedir(3)](/closedir/3.md) functions.

## SEE ALSO

[openat(2)](/openat/2.md), [directory(3)](/directory/3.md), [malloc(3)](/malloc/3.md), [qsort(3)](/qsort/3.md), [strcoll(3)](/strcoll/3.md), [strverscmp(3)](/strverscmp/3.md), [dir(5)](/dir/5.md)

## 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.