scandir(3C)							   scandir(3C)

NAME
       scandir(), alphasort() - scan a directory

SYNOPSIS
DESCRIPTION
       reads  the  directory dirname and builds an array of pointers to direc‐
       tory 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\n");
		      exit(1);
		  }
		  printf("Number of entries is %d\n", 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("\n");
		  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)

Vote for polarhome