1.\" $OpenBSD: scandir.3,v 1.17 2024/04/15 15:47:58 florian Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: April 15 2024 $ 31.Dt SCANDIR 3 32.Os 33.Sh NAME 34.Nm scandir , 35.Nm scandirat , 36.Nm alphasort 37.Nd scan a directory 38.Sh SYNOPSIS 39.In sys/types.h 40.In dirent.h 41.Ft int 42.Fo scandir 43.Fa "const char *dirname" 44.Fa "struct dirent ***namelist" 45.Fa "int (*select)(const struct dirent *)" 46.Fa "int (*compar)(const struct dirent **, const struct dirent **)" 47.Fc 48.Ft int 49.Fo scandirat 50.Fa "int dirfd" 51.Fa "const char *dirname" 52.Fa "struct dirent ***namelist" 53.Fa "int (*select)(const struct dirent *)" 54.Fa "int (*compar)(const struct dirent **, const struct dirent **)" 55.Fc 56.Ft int 57.Fn alphasort "const struct dirent **d1" "const struct dirent **d2" 58.Sh DESCRIPTION 59The 60.Fn scandir 61function reads the directory 62.Fa dirname 63and builds an array of pointers to directory 64entries using 65.Xr malloc 3 . 66It returns the number of entries in the array. 67A pointer to the array of directory entries is stored in the location 68referenced by 69.Fa namelist . 70.Pp 71The 72.Fa select 73parameter is a pointer to a user-supplied subroutine which is called by 74.Fn scandir 75to select which entries are to be included in the array. 76The select routine is passed a 77pointer to a directory entry and should return a non-zero 78value if the directory entry is to be included in the array. 79If 80.Fa select 81is 82.Dv NULL , 83then all directory entries will be included. 84.Pp 85The 86.Fa compar 87parameter is a pointer to a user-supplied subroutine which is passed to 88.Xr qsort 3 89to sort the completed array. 90If this pointer is 91.Dv NULL , 92the array is not sorted. 93.Pp 94The 95.Fn alphasort 96function is a routine which can be used for the 97.Fa compar 98parameter to sort the array alphabetically. 99.Pp 100The memory allocated for the array can be deallocated with 101.Xr free 3 , 102by freeing each pointer in the array and then the array itself. 103.Pp 104The 105.Fn scandirat 106function is similar to 107.Fn scandir , 108but takes an additional 109.Fa dirfd 110argument. 111If 112.Fa dirname 113is relative, 114.Fa dirfd 115must be a valid file descriptor referencing a directory, in which case the 116.Fa dirname 117lookup is performed relative to the directory referenced by 118.Fa dirfd . 119If 120.Fa dirfd 121has the special value 122.Va AT_FDCWD , 123then the current process directory is used as the base for relative lookups. 124See 125.Xr openat 2 126for additional details. 127.Sh DIAGNOSTICS 128Returns \-1 if the directory cannot be opened for reading or if 129.Xr malloc 3 130cannot allocate enough memory to hold all the data structures. 131.Sh SEE ALSO 132.Xr malloc 3 , 133.Xr opendir 3 , 134.Xr qsort 3 , 135.Xr dir 5 136.Sh STANDARDS 137The 138.Fn scandir 139and 140.Fn alphasort 141functions conform to 142.St -p1003.1-2008 . 143.Sh HISTORY 144The 145.Fn scandir 146and 147.Fn alphasort 148functions appeared in 149.Bx 4.2 . 150.Pp 151The argument types for 152.Fn alphasort 153and for the 154.Fa compar 155argument to 156.Fn scandir 157were originally 158.Vt "void *" , 159then changed to 160.Vt "const void *" , 161and then finally changed by 162.St -p1003.1-2008 163to their current form of 164.Vt "const struct dirent **" . 165Similarly, the 166.Fn select 167argument to 168.Fn scandir 169was originally 170.Vt "struct dirent *" 171until it was changed to its current form of 172.Vt "const struct dirent *" . 173