Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
SCANDIR(3)		    Library Functions Manual		    SCANDIR(3)

NAME
       scandir,	 fdscandir,  scandirat,	scandir_b, fdscandir_b,	fdscandirat_b,
       alphasort, versionsort -- scan a	directory

LIBRARY
       Standard	C Library (libc, -lc)

SYNOPSIS
       #include	<dirent.h>

       int
       scandir(const char *dirname,		    struct dirent ***namelist,
	   int (*select)(const struct dirent *),
	   int (*compar)(const struct dirent **, const struct dirent **));

       int
       fdscandir(int dirfd,			    struct dirent ***namelist,
	   int (*select)(const struct dirent *),
	   int (*compar)(const struct dirent **, const struct dirent **));

       int
       scandirat(int dirfd,  const char	*dirname,   struct dirent ***namelist,
	   int (*select)(const struct dirent *),
	   int (*compar)(const struct dirent **, const struct dirent **));

       int
       scandir_b(const char *dirname,		    struct dirent ***namelist,
	   int (^select)(const struct dirent *),
	   int (^compar)(const struct dirent **, const struct dirent **));

       int
       fdscandir_b(int dirfd,			    struct dirent ***namelist,
	   int (^select)(const struct dirent *),
	   int (^compar)(const struct dirent **, const struct dirent **));

       int
       scandirat_b(int dirfd,  const char *dirname, struct dirent ***namelist,
	   int (^select)(const struct dirent *),
	   int (^compar)(const struct dirent **, const struct dirent **));

       int
       alphasort(const struct dirent **d1, const struct	dirent **d2);

       int
       versionsort(const struct	dirent **d1, const struct dirent **d2);

DESCRIPTION
       The scandir() function reads the	directory dirname and builds an	 array
       of  pointers to directory entries using malloc(3).  It returns the num-
       ber of entries in the array.  A pointer to the array of	directory  en-
       tries  is stored	in the location	referenced by namelist (even if	no en-
       tries were selected).

       The select argument is a	pointer	to a user supplied subroutine which is
       called by scandir() to select which entries are to be included  in  the
       array.  The select routine is passed a pointer to a directory entry and
       should return a non-zero	value if the directory entry is	to be included
       in  the	array.	If select is null, then	all the	directory entries will
       be included.

       The compar argument is a	pointer	to a user supplied subroutine which is
       passed to qsort(3) to sort the completed	array.	 If  this  pointer  is
       null, the array is not sorted.

       The  alphasort()	function is a routine which can	be used	for the	compar
       argument	to sort	the array alphabetically using strcoll(3).

       The versionsort() function is a routine	which  can  be	used  for  the
       compar argument to sort the array naturally using strverscmp(3).

       The  memory allocated for the array can be deallocated with free(3), by
       freeing each pointer in the array and then the array itself.

       The fdscandir() function	is similar to scandir(), but takes a file  de-
       scriptor	 referencing a directory instead of a path.  The file descrip-
       tor is left open	on return, regardless of outcome.

       The scandirat() function	is similar to scandir(), but  takes  an	 addi-
       tional  dirfd argument.	If the supplied	dirname	is absolute, the func-
       tion's behavior is identical to that of scandir(), the  dirfd  argument
       is unused.  If dirname is relative, dirfd must be a valid file descrip-
       tor  referencing	 a directory, in which case the	dirname	lookup is per-
       formed relative to the directory	referenced by dirfd.  If dirfd has the
       special value AT_FDCWD, then the	current	process	directory is  used  as
       the base	for relative lookups.  See openat(2) for additional details.

       The  scandir_b(),  fdscandir_b(), and scandirat_b() functions behave in
       the same	way as scandir(), fdscandir(), and scandirat(),	 respectively,
       but  take  blocks  as  arguments	 instead of function pointers and call
       qsort_b() rather	than qsort().

DIAGNOSTICS
       The scandir(), fdscandir(),  scandirat(),  scandir_b(),	fdscandir_b(),
       and  scandirat_b()  functions  return  the  number of directory entries
       found on	succes.	 If the	directory cannot be opened for reading,	an er-
       ror occurs while	reading	the directory, or  malloc(3)  cannot  allocate
       enough memory to	hold all the directory entries,	they return -1 and set
       errno to	an appropriate value.

ERRORS
       The  scandir(),	scandirat(),  scandir_b(), and scandirat_b() functions
       may fail	and set	 errno	for  any  of  the  errors  specified  for  the
       opendir(3), malloc(3), readdir(3), and closedir(3) functions.

       The  fdscandir()	and fdscandir_b() functions may	fail and set errno for
       any  of	the  errors  specified	for   the   fdopendir(3),   malloc(3),
       readdir(3), and closedir(3) functions.

SEE ALSO
       openat(2),     directory(3),	malloc(3),    qsort(3),	   strcoll(3),
       strverscmp(3), dir(5)

STANDARDS
       The alphasort() and scandir() functions are expected to conform to IEEE
       Std 1003.1-2008 ("POSIX.1").  The scandirat() and  versionsort()	 func-
       tions  are GNU extensions and conform to	no standard.  The fdscandir(),
       scandir_b(), fdscandir_b(), and scandirat_b() functions are FreeBSD ex-
       tensions.

HISTORY
       The scandir()  and  alphasort()	functions  appeared  in	 4.2BSD.   The
       scandir_b()  function  was  added in FreeBSD 11.0.  The scandirat() and
       versionsort() functions were added in FreeBSD 13.2.   The  fdscandir(),
       fdscandir_b(), and scandirat_b()	functions were added in	FreeBSD	15.0.

FreeBSD	15.0			 June 25, 2025			    SCANDIR(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=scandir&sektion=3&manpath=FreeBSD+15.0-RELEASE+and+Ports>

home | help