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

NAME

12       alphasort, scandir — scan a directory
13

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

102       An example to print the files in the current directory:
103
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‐2017, <dirent.h>
155
157       Portions of this text are reprinted and reproduced in  electronic  form
158       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
159       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
160       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
161       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
162       event of any discrepancy between this version and the original IEEE and
163       The Open Group Standard, the original IEEE and The Open Group  Standard
164       is  the  referee document. The original Standard can be obtained online
165       at http://www.opengroup.org/unix/online.html .
166
167       Any typographical or formatting errors that appear  in  this  page  are
168       most likely to have been introduced during the conversion of the source
169       files to man page format. To report such errors,  see  https://www.ker
170       nel.org/doc/man-pages/reporting_bugs.html .
171
172
173
174IEEE/The Open Group                  2017                        ALPHASORT(3P)
Impressum