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.\" @(#)scandir.3 8.1 (Berkeley) 6/4/93 29.\" 30.Dd August 31, 2023 31.Dt SCANDIR 3 32.Os 33.Sh NAME 34.Nm scandir , 35.Nm scandirat , 36.Nm scandir_b , 37.Nm alphasort , 38.Nm versionsort 39.Nd scan a directory 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In dirent.h 44.Ft int 45.Fo scandir 46.Fa "const char *dirname" 47.Fa "struct dirent ***namelist" 48.Fa "int \*(lp*select\*(rp\*(lpconst struct dirent *\*(rp" 49.Fa "int \*(lp*compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" 50.Fc 51.Ft int 52.Fo scandirat 53.Fa "int dirfd" 54.Fa "const char *dirname" 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 scandir_b 61.Fa "const char *dirname" 62.Fa "struct dirent ***namelist" 63.Fa "int \*(lp^select\*(rp\*(lpconst struct dirent *\*(rp" 64.Fa "int \*(lp^compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" 65.Fc 66.Ft int 67.Fn alphasort "const struct dirent **d1" "const struct dirent **d2" 68.Ft int 69.Fn versionsort "const struct dirent **d1" "const struct dirent **d2" 70.Sh DESCRIPTION 71The 72.Fn scandir 73function 74reads the directory 75.Fa dirname 76and builds an array of pointers to directory 77entries using 78.Xr malloc 3 . 79It returns the number of entries in the array. 80A pointer to the array of directory entries is stored in the location 81referenced by 82.Fa namelist . 83.Pp 84The 85.Fa select 86argument is a pointer to a user supplied subroutine which is called by 87.Fn scandir 88to select which entries are to be included in the array. 89The select routine is passed a 90pointer to a directory entry and should return a non-zero 91value if the directory entry is to be included in the array. 92If 93.Fa select 94is null, then all the directory entries will be included. 95.Pp 96The 97.Fa compar 98argument is a pointer to a user supplied subroutine which is passed to 99.Xr qsort 3 100to sort the completed array. 101If this pointer is null, the array is not sorted. 102.Pp 103The 104.Fn alphasort 105function 106is a routine which can be used for the 107.Fa compar 108argument to sort the array alphabetically using 109.Xr strcoll 3 . 110.Pp 111The 112.Fn versionsort 113function is a routine which can be used for the 114.Fa compar 115argument to sort the array naturally using 116.Xr strverscmp 3 . 117.Pp 118The memory allocated for the array can be deallocated with 119.Xr free 3 , 120by freeing each pointer in the array and then the array itself. 121.Pp 122The 123.Fn scandirat 124function is similar to 125.Fn scandir , 126but takes an additional 127.Fa dirfd 128argument. 129If the supplied 130.Fa dirname 131is absolute, the function's behavior is identical to that of 132.Fn scandir , 133the 134.Fa dirfd 135argument is unused. 136If 137.Fa dirname 138is relative, 139.Fa dirfd 140must be a valid file descriptor referencing a directory, in 141which case the 142.Fa dirname 143lookup is performed relative to the directory referenced by 144.Fa dirfd . 145If 146.Fa dirfd 147has the special value 148.Va AT_FDCWD , 149then the current process directory is used as the base for 150relative lookups. 151See 152.Xr openat 2 153for additional details. 154.Pp 155The 156.Fn scandir_b 157function behaves in the same way as 158.Fn scandir , 159but takes blocks as arguments instead of function pointers and calls 160.Fn qsort_b 161rather than 162.Fn qsort . 163.Sh DIAGNOSTICS 164Returns \-1 if the directory cannot be opened for reading or if 165.Xr malloc 3 166cannot allocate enough memory to hold all the data structures. 167.Sh SEE ALSO 168.Xr openat 2 , 169.Xr directory 3 , 170.Xr malloc 3 , 171.Xr qsort 3 , 172.Xr strcoll 3 , 173.Xr strverscmp 3 , 174.Xr dir 5 175.Sh STANDARDS 176The 177.Fn versionsort 178function is a GNU extension and conforms to no standard. 179.Sh HISTORY 180The 181.Fn scandir 182and 183.Fn alphasort 184functions appeared in 185.Bx 4.2 . 186The 187.Fn scandirat 188and 189.Fn versionsort 190functions were added in 191.Fx 13.2 . 192