Debian Codegraph @

upstream/debian-unstable/man3/scandir.3

raw
1 '\" t
2 .\" Copyright 1993, David Metcalfe <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\" The pieces on scandirat(3) were copyright and licensed as follows.
8 .\"
9 .\" Copyright 2012, Mark R. Bannister <[email protected]>
10 .\" Copyright 2006, Michael Kerrisk <[email protected]>
11 .\" Copyright, the authors of the Linux man-pages project
12 .\"
13 .\" SPDX-License-Identifier: GPL-2.0-or-later
14 .\"
15 .TH scandir 3 2026-02-08 "Linux man-pages 6.18"
16 .SH NAME
17 scandir, scandirat, alphasort, versionsort \- scan
18 a directory for matching entries
19 .SH LIBRARY
20 Standard C library
21 .RI ( libc ,\~ \-lc )
22 .SH SYNOPSIS
23 .nf
24 .B #include <dirent.h>
25 .P
26 .BI "int scandir(const char *restrict " dirp ,
27 .BI " struct dirent ***restrict " namelist ,
28 .BI " typeof(int (const struct dirent *)) *" filter ,
29 .B " typeof(int (const struct dirent **, const struct dirent **))"
30 .BI " *" compar );
31 .P
32 .BI "int alphasort(const struct dirent **" a ", const struct dirent **" b );
33 .BI "int versionsort(const struct dirent **" a ", const struct dirent **" b );
34 .P
35 .BR "#include <fcntl.h>" " /* Definition of AT_* constants */"
36 .B #include <dirent.h>
37 .P
38 .BI "int scandirat(int " dirfd ", const char *restrict " dirp ,
39 .BI " struct dirent ***restrict " namelist ,
40 .BI " typeof(int (const struct dirent *)) *" filter ,
41 .B " typeof(int (const struct dirent **, const struct dirent **))"
42 .BI " *" compar );
43 .fi
44 .P
45 .RS -4
46 Feature Test Macro Requirements for glibc (see
47 .BR feature_test_macros (7)):
48 .RE
49 .P
50 .BR scandir (),
51 .BR alphasort ():
52 .nf
53 /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200809L
54 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
55 .fi
56 .P
57 .BR versionsort ():
58 .nf
59 _GNU_SOURCE
60 .fi
61 .P
62 .BR scandirat ():
63 .nf
64 _GNU_SOURCE
65 .fi
66 .SH DESCRIPTION
67 The
68 .BR scandir ()
69 function scans the directory
70 .IR dirp ,
71 calling
72 .IR filter ()
73 on each directory entry.
74 Entries for which
75 .IR filter ()
76 returns nonzero are stored in strings allocated via
77 .BR malloc (3),
78 sorted using
79 .BR qsort (3)
80 with the comparison
81 function
82 .IR compar (),
83 and collected in array
84 .I namelist
85 which is allocated via
86 .BR malloc (3).
87 If
88 .I filter
89 is NULL, all entries are selected.
90 .P
91 The
92 .BR alphasort ()
93 and
94 .BR versionsort ()
95 functions can be used as the comparison function
96 .IR compar ().
97 The former sorts directory entries using
98 .BR strcoll (3),
99 the latter using
100 .BR strverscmp (3)
101 on the strings
102 .I (*a)\->d_name
103 and
104 .IR (*b)\->d_name .
105 .SS scandirat()
106 The
107 .BR scandirat ()
108 function operates in exactly the same way as
109 .BR scandir (),
110 except for the differences described here.
111 .P
112 If
113 .I dirp
114 is relative, then it is interpreted relative to the directory
115 referred to by the file descriptor
116 .I dirfd
117 (rather than relative to the current working directory of
118 the calling process, as is done by
119 .BR scandir ()
120 for a relative pathname).
121 .P
122 If
123 .I dirp
124 is relative and
125 .I dirfd
126 is the special value
127 .BR AT_FDCWD ,
128 then
129 .I dirp
130 is interpreted relative to the current working
131 directory of the calling process (like
132 .BR scandir ()).
133 .P
134 If
135 .I dirp
136 is absolute, then
137 .I dirfd
138 is ignored.
139 .P
140 See
141 .BR openat (2)
142 for an explanation of the need for
143 .BR scandirat ().
144 .SH RETURN VALUE
145 The
146 .BR scandir ()
147 function returns the number of directory entries
148 selected.
149 On error, \-1 is returned, with
150 .I errno
151 set to indicate the error.
152 .P
153 The
154 .BR alphasort ()
155 and
156 .BR versionsort ()
157 functions return an integer less than, equal to,
158 or greater than zero if the first argument is considered to be
159 respectively less than, equal to, or greater than the second.
160 .SH ERRORS
161 .TP
162 .B EBADF
163 .RB ( scandirat ())
164 .I dirp
165 is relative but
166 .I dirfd
167 is neither
168 .B AT_FDCWD
169 nor a valid file descriptor.
170 .TP
171 .B ENOENT
172 The path in
173 .I dirp
174 does not exist.
175 .TP
176 .B ENOMEM
177 Insufficient memory to complete the operation.
178 .TP
179 .B ENOTDIR
180 The path in
181 .I dirp
182 is not a directory.
183 .TP
184 .B ENOTDIR
185 .RB ( scandirat ())
186 .I dirp
187 is relative and
188 .I dirfd
189 is a file descriptor referring to a file other than a directory.
190 .SH ATTRIBUTES
191 For an explanation of the terms used in this section, see
192 .BR attributes (7).
193 .TS
194 allbox;
195 lbx lb lb
196 l l l.
197 Interface Attribute Value
198 T{
199 .na
200 .nh
201 .BR scandir (),
202 .BR scandirat ()
203 T} Thread safety MT-Safe
204 T{
205 .na
206 .nh
207 .BR alphasort (),
208 .BR versionsort ()
209 T} Thread safety MT-Safe locale
210 .TE
211 .SH STANDARDS
212 .TP
213 .BR alphasort ()
214 .TQ
215 .BR scandir ()
216 POSIX.1-2008.
217 .TP
218 .BR versionsort ()
219 .TQ
220 .BR scandirat ()
221 GNU.
222 .SH HISTORY
223 .TP
224 .BR alphasort ()
225 .TQ
226 .BR scandir ()
227 4.3BSD, POSIX.1-2008.
228 .TP
229 .BR versionsort ()
230 glibc 2.1.
231 .TP
232 .BR scandirat ()
233 glibc 2.15.
234 .\" .P
235 .\" The functions
236 .\" .BR scandir ()
237 .\" and
238 .\" .BR alphasort ()
239 .\" are from 4.3BSD, and have been available under Linux since libc4.
240 .\" Libc4 and libc5 use the more precise prototype
241 .\" .sp
242 .\" .nf
243 .\" int alphasort(const struct dirent ** a,
244 .\" const struct dirent **b);
245 .\" .fi
246 .\" .sp
247 .\" but glibc 2.0 returns to the imprecise BSD prototype.
248 .SH NOTES
249 Since glibc 2.1,
250 .BR alphasort ()
251 calls
252 .BR strcoll (3);
253 earlier it used
254 .BR strcmp (3).
255 .P
256 Before glibc 2.10, the two arguments of
257 .BR alphasort ()
258 and
259 .BR versionsort ()
260 were typed as
261 .IR "const void\ *" .
262 When
263 .BR alphasort ()
264 was standardized in POSIX.1-2008,
265 the argument type was specified as the type-safe
266 .IR "const struct dirent\ **",
267 and glibc 2.10 changed the definition of
268 .BR alphasort ()
269 (and the nonstandard
270 .BR versionsort ())
271 to match the standard.
272 .SH EXAMPLES
273 The program below prints a list of the files in the current directory
274 in reverse order.
275 .\"
276 .SS Program source
277 \&
278 .\" SRC BEGIN (scandir.c)
279 .EX
280 #define _DEFAULT_SOURCE
281 #include <dirent.h>
282 #include <stdio.h>
283 #include <stdlib.h>
284 \&
285 int
286 main(void)
287 {
288 struct dirent **namelist;
289 int n;
290 \&
291 n = scandir(".", &namelist, NULL, alphasort);
292 if (n == \-1) {
293 perror("scandir");
294 exit(EXIT_FAILURE);
295 }
296 \&
297 while (n\-\-) {
298 printf("%s\[rs]n", namelist[n]\->d_name);
299 free(namelist[n]);
300 }
301 free(namelist);
302 \&
303 exit(EXIT_SUCCESS);
304 }
305 .EE
306 .\" SRC END
307 .SH SEE ALSO
308 .BR closedir (3),
309 .BR fnmatch (3),
310 .BR opendir (3),
311 .BR readdir (3),
312 .BR rewinddir (3),
313 .BR seekdir (3),
314 .BR strcmp (3),
315 .BR strcoll (3),
316 .BR strverscmp (3),
317 .BR telldir (3)