1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)scandir.3 8.1 (Berkeley) 06/04/93 7.\" 8.Dd 9.Dt SCANDIR 3 10.Os BSD 4.2 11.Sh NAME 12.Nm scandir , 13.Nm alphasort 14.Nd scan a directory 15.Sh SYNOPSIS 16.Fd #include <sys/types.h> 17.Fd #include <dirent.h> 18.Ft int 19.Fn scandir "const char *dirname" "struct dirent ***namelist" "int \\*(lp*select\\*(rp\\*(lpstruct dirent *\\*(rp" "int \\*(lp*compar\\*(rp\\*(lpconst void *, const void *\\*(rp" 20.Ft int 21.Fn alphasort "const void *d1" "const void *d2" 22.Sh DESCRIPTION 23The 24.Fn scandir 25function 26reads the directory 27.Fa dirname 28and builds an array of pointers to directory 29entries using 30.Xr malloc 3 . 31It returns the number of entries in the array. 32A pointer to the array of directory entries is stored in the location 33referenced by 34.Fa namelist . 35.Pp 36The 37.Fa select 38parameter is a pointer to a user supplied subroutine which is called by 39.Fn scandir 40to select which entries are to be included in the array. 41The select routine is passed a 42pointer to a directory entry and should return a non-zero 43value if the directory entry is to be included in the array. 44If 45.Fa select 46is null, then all the directory entries will be included. 47.Pp 48The 49.Fa compar 50parameter is a pointer to a user supplied subroutine which is passed to 51.Xr qsort 3 52to sort the completed array. 53If this pointer is null, the array is not sorted. 54.Pp 55The 56.Fn alphasort 57function 58is a routine which can be used for the 59.Fa compar 60parameter to sort the array alphabetically. 61.Pp 62The memory allocated for the array can be deallocated with 63.Xr free 3 , 64by freeing each pointer in the array and then the array itself. 65.Sh DIAGNOSTICS 66Returns \-1 if the directory cannot be opened for reading or if 67.Xr malloc 3 68cannot allocate enough memory to hold all the data structures. 69.Sh SEE ALSO 70.Xr directory 3 , 71.Xr malloc 3 , 72.Xr qsort 3 , 73.Xr dir 5 74.Sh HISTORY 75The 76.Fn scandir 77and 78.Fn alphasort 79functions appeared in 80.Bx 4.2 . 81