# alphasort

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           alphasort, scandir — scan a directory
    


## SYNOPSIS



           #include <dirent.h>
    
           int alphasort(const struct dirent **_d1_ , const struct dirent **_d2_);
           int scandir(const char *_dir_ , struct dirent ***_namelist_ ,
               int (*_sel_)(const struct dirent *),
               int (*_compar_)(const struct dirent **, const struct dirent **));
    


## DESCRIPTION



           The _alphasort_() function can be used as the comparison function
           for the _scandir_() function to sort the directory entries, _d1_ and
           _d2_ , into alphabetical order. Sorting happens as if by calling the
           _strcoll_() function on the _d_name_ element of the **dirent** structures
           passed as the two parameters. If the _strcoll_() function fails, the
           return value of _alphasort_() is unspecified.
    
           The _alphasort_() function shall not change the setting of _errno_ if
           successful. Since no return value is reserved to indicate an
           error, an application wishing to check for error situations should
           set _errno_ to 0, then call _alphasort_(), then check _errno_.
    
           The _scandir_() function shall scan the directory _dir_ , calling the
           function referenced by _sel_ on each directory entry. Entries for
           which the function referenced by _sel_ returns non-zero shall be
           stored in strings allocated as if by a call to _malloc_(), and
           sorted as if by a call to _qsort_() with the comparison function
           _compar_ , except that _compar_ need not provide total ordering. The
           strings are collected in array _namelist_ which shall be allocated
           as if by a call to _malloc_().  If _sel_ is a null pointer, all
           entries shall be selected.  If the comparison function _compar_ does
           not provide total ordering, the order in which the directory
           entries are stored is unspecified.
    


## RETURN VALUE



           Upon successful completion, the _alphasort_() function shall return
           an integer greater than, equal to, or less than 0, according to
           whether the name of the directory entry pointed to by _d1_ is
           lexically greater than, equal to, or less than the directory
           pointed to by _d2_ when both are interpreted as appropriate to the
           current locale. There is no return value reserved to indicate an
           error.
    
           Upon successful completion, the _scandir_() function shall return
           the number of entries in the array and a pointer to the array
           through the parameter _namelist_.  Otherwise, the _scandir_() function
           shall return -1.
    


## ERRORS



           The _scandir_() function shall fail if:
    
           **EACCES** Search permission is denied for the component of the path
                  prefix of _dir_ or read permission is denied for _dir_.
    
           **ELOOP** A loop exists in symbolic links encountered during
                  resolution of the _dir_ argument.
    
           **ENAMETOOLONG**
                  The length of a component of a pathname is longer than
                  {NAME_MAX}.
    
           **ENOENT** A component of _dir_ does not name an existing directory or
                  _dir_ is an empty string.
    
           **ENOMEM** Insufficient storage space is available.
    
           **ENOTDIR**
                  A component of _dir_ names an existing file that is neither a
                  directory nor a symbolic link to a directory.
    
           **EOVERFLOW**
                  One of the values to be returned or passed to a callback
                  function cannot be represented correctly.
    
           The _scandir_() function may fail if:
    
           **ELOOP** More than {SYMLOOP_MAX} symbolic links were encountered
                  during resolution of the _dir_ argument.
    
           **EMFILE** All file descriptors available to the process are currently
                  open.
    
           **ENAMETOOLONG**
                  The length of a pathname exceeds {PATH_MAX}, or pathname
                  resolution of a symbolic link produced an intermediate
                  result with a length that exceeds {PATH_MAX}.
    
           **ENFILE** Too many files are currently open in the system.
    
           _The following sections are informative._
    


## EXAMPLES



           An example to print the files in the current directory:
    
               #include <dirent.h>
               #include <stdio.h>
               #include <stdlib.h>
               ...
               struct dirent **namelist;
               int i,n;
    
                   n = scandir(".", &namelist, 0, alphasort);
                   if (n < 0)
                       perror("scandir");
                   else {
                       for (i = 0; i < n; i++) {
                           printf("%s\n", namelist[i]->d_name);
                           free(namelist[i]);
                           }
                       }
                   free(namelist);
               ...
    


## APPLICATION USAGE



           If _dir_ contains filenames that do not form character strings, or
           which contain characters outside the domain of the collating
           sequence of the current locale, the _alphasort_() function need not
           provide a total ordering. This condition is not possible if all
           filenames within the directory consist only of characters from the
           portable filename character set.
    
           The _scandir_() function may allocate dynamic storage during its
           operation. If _scandir_() is forcibly terminated, such as by
           _longjmp_() or _siglongjmp_() being executed by the function pointed
           to by _sel_ or _compar_ , or by an interrupt routine, _scandir_() does
           not have a chance to free that storage, so it remains permanently
           allocated. A safe way to handle interrupts is to store the fact
           that an interrupt has occurred, then wait until _scandir_() returns
           to act on the interrupt.
    
           For functions that allocate memory as if by _malloc_(), the
           application should release such memory when it is no longer
           required by a call to _free_().  For _scandir_(), this is _namelist_
           (including all of the individual strings in _namelist_).
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *