scandir

Purpose

     Scans a directory.

Library

     Berkeley Library (libbsd.a)

Syntax

     #include <bsd/sys/types.h>
     #include <bsd/sys/dir.h>

     int scandir (dirname, namelist, select, compar)
     char *dirname;
     struct direct * (*namelist[ ]);
     int  (*select) ( );
     int  (*compar) ( );

Description

     The scandir subroutine reads  the directory pointed to by
     dirname,  then uses  the malloc  subroutine to  create an
     array of pointers to directory entries.  The scandir sub-
     routine returns the  number of entries in  the array and,
     through the namelist parameter, a pointer to the array.

     The select parameter points to a user-supplied subroutine
     that  is called  by scandir  to select  which entries  to
     include in the array.  The  selection routine is passed a
     pointer to a directory entry and should return a non-zero
     value  for a  directory  entry that  is  included in  the
     array.   If select  is  NULL, all  directory entries  are
     included.

     The compar parameter also  points to a user-supplied sub-
     routine.  This  routine is  passed to  qsort to  sort the
     completed array.   If compar  is NULL,  the array  is not
     sorted.   The  alphasort subroutine  provides  comparison
     functions for sorting alphabetically and can be specified
     by the compar parameter.  (See "alphasort.")

     The memory allocated  to the array can  be deallocated by
     freeing each pointer  in the array and  the array itself,
     with the free subroutine.  (For more information on free,
     see "malloc, free, realloc, calloc.")

Return Value

     The scandir subroutine returns the value -1 if the direc-
     tory cannot be opened for  reading, or if the malloc sub-
     routine  cannot allocate  enough memory  to hold  all the
     data structures.   If successful, the  scandir subroutine
     returns the number of entries found.

Related Information

     In this book:  "alphasort,"  "directory,"  "malloc, free,
     realloc, calloc," "qsort," and  "dir."