# scandir

## NAME



           scandir, scandirat, alphasort, versionsort - scan a directory for
           matching entries
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <dirent.h>**
    
           **int scandir(const char *restrict** _dirp_**,**
                       **struct dirent ***restrict** _namelist_**,**
                       **typeof(int (const struct dirent *)) ***_filter_**,**
                       **typeof(int (const struct dirent **, const struct dirent **))**
                           *****_compar_**);**
    
           **int alphasort(const struct dirent ****_a_**, const struct dirent ****_b_**);**
           **int versionsort(const struct dirent ****_a_**, const struct dirent ****_b_**);**
    
           **#include <fcntl.h>          **/* Definition of AT_* constants */
           **#include <dirent.h>**
    
           **int scandirat(int** _dirfd_**, const char *restrict** _dirp_**,**
                       **struct dirent ***restrict** _namelist_**,**
                       **typeof(int (const struct dirent *)) ***_filter_**,**
                       **typeof(int (const struct dirent **, const struct dirent **))**
                           *****_compar_**);**
    
       Feature Test Macro Requirements for glibc (see
       feature_test_macros(7)):
    
           **scandir**(), **alphasort**():
               /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200809L
                   || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
    
           **versionsort**():
               _GNU_SOURCE
    
           **scandirat**():
               _GNU_SOURCE
    


## DESCRIPTION



           The **scandir**() function scans the directory _dirp_ , calling _filter_()
           on each directory entry.  Entries for which _filter_() returns
           nonzero are stored in strings allocated via malloc(3), sorted
           using qsort(3) with the comparison function _compar_(), and
           collected in array _namelist_ which is allocated via malloc(3).  If
           _filter_ is NULL, all entries are selected.
    
           The **alphasort**() and **versionsort**() functions can be used as the
           comparison function _compar_().  The former sorts directory entries
           using strcoll(3), the latter using strverscmp(3) on the strings
           _(*a)- >d_name_ and _(*b)- >d_name_.
    
       **scandirat()**
           The **scandirat**() function operates in exactly the same way as
           **scandir**(), except for the differences described here.
    
           If _dirp_ is relative, then it is interpreted relative to the
           directory referred to by the file descriptor _dirfd_ (rather than
           relative to the current working directory of the calling process,
           as is done by **scandir**() for a relative pathname).
    
           If _dirp_ is relative and _dirfd_ is the special value **AT_FDCWD** , then
           _dirp_ is interpreted relative to the current working directory of
           the calling process (like **scandir**()).
    
           If _dirp_ is absolute, then _dirfd_ is ignored.
    
           See openat(2) for an explanation of the need for **scandirat**().
    


## RETURN VALUE



           The **scandir**() function returns the number of directory entries
           selected.  On error, -1 is returned, with _errno_ set to indicate
           the error.
    
           The **alphasort**() and **versionsort**() functions return an integer less
           than, equal to, or greater than zero if the first argument is
           considered to be respectively less than, equal to, or greater than
           the second.
    


## ERRORS



           **EBADF**(**scandirat**()) _dirp_ is relative but _dirfd_ is neither
                  **AT_FDCWD** nor a valid file descriptor.
    
           **ENOENT** The path in _dirp_ does not exist.
    
           **ENOMEM** Insufficient memory to complete the operation.
    
           **ENOTDIR**
                  The path in _dirp_ is not a directory.
    
           **ENOTDIR**
                  (**scandirat**()) _dirp_ is relative and _dirfd_ is a file
                  descriptor referring to a file other than a directory.
    


## ATTRIBUTES



           For an explanation of the terms used in this section, see
           attributes(7).
           ┌───────────────────────────────┬───────────────┬────────────────┐
           │ **Interface** │ **Attribute** │ **Value** │
           ├───────────────────────────────┼───────────────┼────────────────┤
           │ **scandir**(), **scandirat**()        │ Thread safety │ MT-Safe        │
           ├───────────────────────────────┼───────────────┼────────────────┤
           │ **alphasort**(), **versionsort**()    │ Thread safety │ MT-Safe locale │
           └───────────────────────────────┴───────────────┴────────────────┘
    


## STANDARDS



           **alphasort**()
           **scandir**()
                  POSIX.1-2008.
    
           **versionsort**()
           **scandirat**()
                  GNU.
    


## NOTES



           Since glibc 2.1, **alphasort**() calls strcoll(3); earlier it used
           strcmp(3).
    
           Before glibc 2.10, the two arguments of **alphasort**() and
           **versionsort**() were typed as _const void *_.  When **alphasort**() was
           standardized in POSIX.1-2008, the argument type was specified as
           the type-safe _const struct dirent **_ , and glibc 2.10 changed the
           definition of **alphasort**() (and the nonstandard **versionsort**()) to
           match the standard.
    


## EXAMPLES



           The program below prints a list of the files in the current
           directory in reverse order.
    
       **Program source**
    
           #define _DEFAULT_SOURCE
           #include <dirent.h>
           #include <stdio.h>
           #include <stdlib.h>
    
           int
           main(void)
           {
               struct dirent **namelist;
               int n;
    
               n = scandir(".", &namelist, NULL, alphasort);
               if (n == -1) {
                   perror("scandir");
                   exit(EXIT_FAILURE);
               }
    
               while (n--) {
                   printf("%s\n", namelist[n]->d_name);
                   free(namelist[n]);
               }
               free(namelist);
    
               exit(EXIT_SUCCESS);
           }
    


* * *