1ALPHASORT(3P)              POSIX Programmer's Manual             ALPHASORT(3P)
2
3
4

PROLOG

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

NAME

13       alphasort, scandir — scan a directory
14

SYNOPSIS

16       #include <dirent.h>
17
18       int alphasort(const struct dirent **d1, const struct dirent **d2);
19       int scandir(const char *dir, struct dirent ***namelist,
20           int (*sel)(const struct dirent *),
21           int (*compar)(const struct dirent **, const struct dirent **));
22

DESCRIPTION

24       The alphasort() function can be used as the comparison function for the
25       scandir()  function  to  sort  the  directory  entries, d1 and d2, into
26       alphabetical order. Sorting happens as  if  by  calling  the  strcoll()
27       function  on  the d_name element of the dirent structures passed as the
28       two parameters. If the strcoll() function fails, the  return  value  of
29       alphasort() is unspecified.
30
31       The  alphasort() function shall not change the setting of errno if suc‐
32       cessful. Since no return value is reserved to  indicate  an  error,  an
33       application  wishing  to check for error situations should set errno to
34       0, then call alphasort(), then check errno.
35
36       The scandir() function shall scan the directory dir, calling the  func‐
37       tion  referenced  by sel on each directory entry. Entries for which the
38       function referenced by sel returns non-zero shall be stored in  strings
39       allocated  as  if  by a call to malloc(), and sorted as if by a call to
40       qsort() with the comparison function compar, except  that  compar  need
41       not provide total ordering. The strings are collected in array namelist
42       which shall be allocated as if by a call to malloc().  If sel is a null
43       pointer,  all  entries  shall  be selected.  If the comparison function
44       compar does not provide total ordering, the order in which  the  direc‐
45       tory entries are stored is unspecified.
46

RETURN VALUE

48       Upon  successful  completion,  the alphasort() function shall return an
49       integer greater than, equal to, or less than 0,  according  to  whether
50       the  name  of the directory entry pointed to by d1 is lexically greater
51       than, equal to, or less than the directory pointed to by d2  when  both
52       are  interpreted  as  appropriate  to  the  current locale. There is no
53       return value reserved to indicate an error.
54
55       Upon successful completion, the scandir()  function  shall  return  the
56       number  of  entries in the array and a pointer to the array through the
57       parameter namelist.  Otherwise, the scandir() function shall return −1.
58

ERRORS

60       The scandir() function shall fail if:
61
62       EACCES Search permission is denied for the component of the path prefix
63              of dir or read permission is denied for dir.
64
65       ELOOP  A loop exists in symbolic links encountered during resolution of
66              the dir argument.
67
68       ENAMETOOLONG
69              The  length  of  a  component  of  a  pathname  is  longer  than
70              {NAME_MAX}.
71
72       ENOENT A component of dir does not name an existing directory or dir is
73              an empty string.
74
75       ENOMEM Insufficient storage space is available.
76
77       ENOTDIR
78              A component of dir names an existing  file  that  is  neither  a
79              directory nor a symbolic link to a directory.
80
81       EOVERFLOW
82              One  of  the values to be returned or passed to a callback func‐
83              tion cannot be represented correctly.
84
85       The scandir() function may fail if:
86
87       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered  during
88              resolution of the dir argument.
89
90       EMFILE All  file  descriptors  available  to  the process are currently
91              open.
92
93       ENAMETOOLONG
94              The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
95              tion  of  a symbolic link produced an intermediate result with a
96              length that exceeds {PATH_MAX}.
97
98       ENFILE Too many files are currently open in the system.
99
100       The following sections are informative.
101

EXAMPLES

103       An example to print the files in the current directory:
104
105           #include <dirent.h>
106           #include <stdio.h>
107           #include <stdlib.h>
108           ...
109           struct dirent **namelist;
110           int i,n;
111
112               n = scandir(".", &namelist, 0, alphasort);
113               if (n < 0)
114                   perror("scandir");
115               else {
116                   for (i = 0; i < n; i++) {
117                       printf("%s\n", namelist[i]->d_name);
118                       free(namelist[i]);
119                       }
120                   }
121               free(namelist);
122           ...
123

APPLICATION USAGE

125       If dir contains filenames that do not form character strings, or  which
126       contain  characters outside the domain of the collating sequence of the
127       current locale, the alphasort()  function  need  not  provide  a  total
128       ordering.  This  condition  is not possible if all filenames within the
129       directory consist only of characters from the portable filename charac‐
130       ter set.
131
132       The  scandir()  function may allocate dynamic storage during its opera‐
133       tion. If scandir() is forcibly terminated, such as by longjmp() or sig‐
134       longjmp()  being  executed by the function pointed to by sel or compar,
135       or by an interrupt routine, scandir() does not have a  chance  to  free
136       that storage, so it remains permanently allocated. A safe way to handle
137       interrupts is to store the fact that an interrupt  has  occurred,  then
138       wait until scandir() returns to act on the interrupt.
139
140       For  functions  that allocate memory as if by malloc(), the application
141       should release such memory when it is no longer required by a  call  to
142       free().  For scandir(), this is namelist (including all of the individ‐
143       ual strings in namelist).
144

RATIONALE

146       None.
147

FUTURE DIRECTIONS

149       None.
150

SEE ALSO

152       qsort(), strcoll()
153
154       The Base Definitions volume of POSIX.1‐2008, <dirent.h>
155
157       Portions of this text are reprinted and reproduced in  electronic  form
158       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
159       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
160       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
161       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
162       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
163       event of any discrepancy between this version and the original IEEE and
164       The  Open Group Standard, the original IEEE and The Open Group Standard
165       is the referee document. The original Standard can be  obtained  online
166       at http://www.unix.org/online.html .
167
168       Any  typographical  or  formatting  errors that appear in this page are
169       most likely to have been introduced during the conversion of the source
170       files  to  man page format. To report such errors, see https://www.ker
171       nel.org/doc/man-pages/reporting_bugs.html .
172
173
174
175IEEE/The Open Group                  2013                        ALPHASORT(3P)
Impressum