scandir(3C)															       scandir(3C)

NAME

       scandir(), alphasort() - scan a directory

SYNOPSIS

DESCRIPTION

       reads  the directory dirname and builds an array of pointers to directory entries using (see malloc(3C)).  It returns the number of entries
       in the array and a pointer to the array through namelist.

       The select parameter is a pointer to a user-supplied subroutine which is called by 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 parameter is a pointer to a user-supplied subroutine which is passed to qsort(3C) to sort the completed array.  If this  pointer
       is null, the array is not sorted.  is a routine which can be used for the compar parameter to sort the array alphabetically.

EXTERNAL INFLUENCES

   Locale
       The category determines the collation ordering used by

       The  category  determines the interpretation of bytes in the file name portion of directory entries as single- and/or multi-byte characters
       by the function.

       Results are undefined if the locales specified by the and categories use different code sets.

   International Code Set Support
       Single- and multi-byte character code sets are supported for

RETURN VALUE

       If successful, returns the number of directory entries selected, and through the  namelist  parameter  returns  a  pointer  to  the  array.
       returns -1, if the directory cannot be opened for reading or cannot allocate enough memory to hold all the data structures.

APPLICATION USAGE

       uses  to  allocate memory for the array associated with the namelist pointer.  If the return value of is greater than or equal to zero(0),
       memory allocated for the namelist pointer needs to be freed by the application using (see malloc(3C)) by first freeing each pointer in  the
       array followed by the array itself.

EXAMPLES

       The  example  program  below  scans the directory.  It does not exclude any entries since select is NULL.  The contents of are sorted by It
       prints out how many entries are in and the sorted entries of the directory.  The memory used by is returned using

	      #include <sys/types.h>
	      #include <stdio.h>
	      #include <dirent.h>

	      extern int scandir();
	      extern int alphasort();

	      main()
	      {
		  int num_entries, i;
		  struct dirent **namelist, **list;

		  if ((num_entries =
			   scandir("/tmp", &namelist, NULL, alphasort)) < 0) {
		      fprintf(stderr, "Unexpected error
");
		      exit(1);
		  }
		  printf("Number of entries is %d
", num_entries);
		  if (num_entries) {
		      printf("Entries are:");
		      for (i=0, list=namelist; i<num_entries; i++) {
			  printf(" %s", (*list)->d_name);
			  free(*list);
			  list++;
		      }
		  }
		  free(namelist);
		  printf("
");
		  exit(0);
	      }

WARNINGS

       For 32-bit applications, the d_ino field of the struct returned by or may overflow for filesystems that use 64-bit values.   In	this  case
       the most-significant bytes will be truncated without generating an error and d_ino values may not be unique.

SEE ALSO

       directory(3C), malloc(3C), qsort(3C), string(3C), dirent(5), thread_safety(5).

																       scandir(3C)