huschi.net

ALPHASORT(3P)              POSIX Programmer's Manual             ALPHASORT(3P)
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 suc-
       cessful. 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  func-
       tion  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  direc-
       tory 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 func-
              tion 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 resolu-
              tion  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 charac-
       ter set.
       The  scandir()  function may allocate dynamic storage during its opera-
       tion. If scandir() is forcibly terminated, such as by longjmp() or sig-
       longjmp()  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 individ-
       ual strings in namelist).
RATIONALE
       None.
FUTURE DIRECTIONS
       None.
SEE ALSO
       qsort(), strcoll()
       The Base Definitions volume of POSIX.1-2008, <dirent.h>
COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri-
       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
       event of any discrepancy between this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be  obtained  online
       at http://www.unix.org/online.html .
       Any  typographical  or  formatting  errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files  to  man page format. To report such errors, see https://www.ker-
       nel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group                  2013                        ALPHASORT(3P)