man3/scandir.3

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