1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd June 25, 2025 29.Dt SCANDIR 3 30.Os 31.Sh NAME 32.Nm scandir , 33.Nm fdscandir , 34.Nm scandirat , 35.Nm scandir_b , 36.Nm fdscandir_b , 37.Nm fdscandirat_b , 38.Nm alphasort , 39.Nm versionsort 40.Nd scan a directory 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In dirent.h 45.Ft int 46.Fo scandir 47.Fa "const char *dirname" 48.Fa "struct dirent ***namelist" 49.Fa "int \*(lp*select\*(rp\*(lpconst struct dirent *\*(rp" 50.Fa "int \*(lp*compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" 51.Fc 52.Ft int 53.Fo fdscandir 54.Fa "int dirfd" 55.Fa "struct dirent ***namelist" 56.Fa "int \*(lp*select\*(rp\*(lpconst struct dirent *\*(rp" 57.Fa "int \*(lp*compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" 58.Fc 59.Ft int 60.Fo scandirat 61.Fa "int dirfd" 62.Fa "const char *dirname" 63.Fa "struct dirent ***namelist" 64.Fa "int \*(lp*select\*(rp\*(lpconst struct dirent *\*(rp" 65.Fa "int \*(lp*compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" 66.Fc 67.Ft int 68.Fo scandir_b 69.Fa "const char *dirname" 70.Fa "struct dirent ***namelist" 71.Fa "int \*(lp^select\*(rp\*(lpconst struct dirent *\*(rp" 72.Fa "int \*(lp^compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" 73.Fc 74.Ft int 75.Fo fdscandir_b 76.Fa "int dirfd" 77.Fa "struct dirent ***namelist" 78.Fa "int \*(lp^select\*(rp\*(lpconst struct dirent *\*(rp" 79.Fa "int \*(lp^compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" 80.Fc 81.Ft int 82.Fo scandirat_b 83.Fa "int dirfd" 84.Fa "const char *dirname" 85.Fa "struct dirent ***namelist" 86.Fa "int \*(lp^select\*(rp\*(lpconst struct dirent *\*(rp" 87.Fa "int \*(lp^compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" 88.Fc 89.Ft int 90.Fn alphasort "const struct dirent **d1" "const struct dirent **d2" 91.Ft int 92.Fn versionsort "const struct dirent **d1" "const struct dirent **d2" 93.Sh DESCRIPTION 94The 95.Fn scandir 96function 97reads the directory 98.Fa dirname 99and builds an array of pointers to directory 100entries using 101.Xr malloc 3 . 102It returns the number of entries in the array. 103A pointer to the array of directory entries is stored in the location 104referenced by 105.Fa namelist 106(even if no entries were selected). 107.Pp 108The 109.Fa select 110argument is a pointer to a user supplied subroutine which is called by 111.Fn scandir 112to select which entries are to be included in the array. 113The select routine is passed a 114pointer to a directory entry and should return a non-zero 115value if the directory entry is to be included in the array. 116If 117.Fa select 118is null, then all the directory entries will be included. 119.Pp 120The 121.Fa compar 122argument is a pointer to a user supplied subroutine which is passed to 123.Xr qsort 3 124to sort the completed array. 125If this pointer is null, the array is not sorted. 126.Pp 127The 128.Fn alphasort 129function 130is a routine which can be used for the 131.Fa compar 132argument to sort the array alphabetically using 133.Xr strcoll 3 . 134.Pp 135The 136.Fn versionsort 137function is a routine which can be used for the 138.Fa compar 139argument to sort the array naturally using 140.Xr strverscmp 3 . 141.Pp 142The memory allocated for the array can be deallocated with 143.Xr free 3 , 144by freeing each pointer in the array and then the array itself. 145.Pp 146The 147.Fn fdscandir 148function is similar to 149.Fn scandir , 150but takes a file descriptor referencing a directory instead of a path. 151The file descriptor is left open on return, regardless of outcome. 152.Pp 153The 154.Fn scandirat 155function is similar to 156.Fn scandir , 157but takes an additional 158.Fa dirfd 159argument. 160If the supplied 161.Fa dirname 162is absolute, the function's behavior is identical to that of 163.Fn scandir , 164the 165.Fa dirfd 166argument is unused. 167If 168.Fa dirname 169is relative, 170.Fa dirfd 171must be a valid file descriptor referencing a directory, in 172which case the 173.Fa dirname 174lookup is performed relative to the directory referenced by 175.Fa dirfd . 176If 177.Fa dirfd 178has the special value 179.Va AT_FDCWD , 180then the current process directory is used as the base for 181relative lookups. 182See 183.Xr openat 2 184for additional details. 185.Pp 186The 187.Fn scandir_b , 188.Fn fdscandir_b , 189and 190.Fn scandirat_b 191functions behave in the same way as 192.Fn scandir , 193.Fn fdscandir , 194and 195.Fn scandirat , 196respectively, 197but take blocks as arguments instead of function pointers and call 198.Fn qsort_b 199rather than 200.Fn qsort . 201.Sh DIAGNOSTICS 202The 203.Fn scandir , 204.Fn fdscandir , 205.Fn scandirat , 206.Fn scandir_b , 207.Fn fdscandir_b , 208and 209.Fn scandirat_b 210functions return the number of directory entries found on succes. 211If the directory cannot be opened for reading, an error occurs 212while reading the directory, or 213.Xr malloc 3 214cannot allocate enough memory to hold all the directory entries, 215they return \-1 and set 216.Va errno 217to an appropriate value. 218.Sh ERRORS 219The 220.Fn scandir , 221.Fn scandirat , 222.Fn scandir_b , 223and 224.Fn scandirat_b 225functions may fail and set 226.Va errno 227for any of the errors specified for the 228.Xr opendir 3 , 229.Xr malloc 3 , 230.Xr readdir 3 , 231and 232.Xr closedir 3 233functions. 234.Pp 235The 236.Fn fdscandir 237and 238.Fn fdscandir_b 239functions may fail and set 240.Va errno 241for any of the errors specified for the 242.Xr fdopendir 3 , 243.Xr malloc 3 , 244.Xr readdir 3 , 245and 246.Xr closedir 3 247functions. 248.Sh SEE ALSO 249.Xr openat 2 , 250.Xr directory 3 , 251.Xr malloc 3 , 252.Xr qsort 3 , 253.Xr strcoll 3 , 254.Xr strverscmp 3 , 255.Xr dir 5 256.Sh STANDARDS 257The 258.Fn alphasort 259and 260.Fn scandir 261functions are expected to conform to 262.St -p1003.1-2008 . 263The 264.Fn scandirat 265and 266.Fn versionsort 267functions are GNU extensions and conform to no standard. 268The 269.Fn fdscandir , 270.Fn scandir_b , 271.Fn fdscandir_b , 272and 273.Fn scandirat_b 274functions are 275.Fx 276extensions. 277.Sh HISTORY 278The 279.Fn scandir 280and 281.Fn alphasort 282functions appeared in 283.Bx 4.2 . 284The 285.Fn scandir_b 286function was added in 287.Fx 11.0 . 288The 289.Fn scandirat 290and 291.Fn versionsort 292functions were added in 293.Fx 13.2 . 294The 295.Fn fdscandir , 296.Fn fdscandir_b , 297and 298.Fn scandirat_b 299functions were added in 300.Fx 15.0 . 301