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 number of
     entries in the array.  A pointer to  the  array  of  directory  entries  is
     stored  in the location referenced by namelist (even if no entries were se-
     lected).

     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 ar-
     ray.  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  in-
     cluded.

     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 ar-
     gument 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 descrip-
     tor referencing a directory instead of a path.  The file descriptor is left
     open on return, regardless of outcome.

     The scandirat() function is similar to scandir(), but takes  an  additional
     dirfd argument.  If the supplied dirname is absolute, the function's behav-
     ior  is  identical  to that of scandir(), the dirfd argument is unused.  If
     dirname is relative, dirfd must be a valid file  descriptor  referencing  a
     directory,  in  which  case the dirname lookup is performed 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  error  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  appro-
     priate 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), mal-
     loc(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() functions are
     GNU extensions and conform to no standard.  The  fdscandir(),  scandir_b(),
     fdscandir_b(), and scandirat_b() functions are FreeBSD extensions.

HISTORY
     The  scandir()  and  alphasort()  functions  appeared in 4.2BSD.  The scan-
     dir_b() function was added in FreeBSD 11.0.  The scandirat()  and	version-
     sort()  functions	were  added  in  FreeBSD 13.2.	The fdscandir(), fdscan-
     dir_b(), and scandirat_b() functions were added in FreeBSD 15.0.

FreeBSD ports 15.quarterly	  June 25, 2025 		      SCANDIR(3)

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

home | help