gen/scandir.3

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)scandir.3   8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/gen/scandir.3,v 1.8 2002/12/19 09:40:21 ru Exp $
  34 .\"
  35 .Dd May 20, 2008
  36 .Dt SCANDIR 3
  37 .Os
  38 .Sh NAME
  39 .Nm scandir ,
  40 #ifdef UNIFDEF_BLOCKS
  41 .Nm scandir_b ,
  42 #endif
  43 .Nm alphasort
  44 .Nd scan a directory
  45 .Sh SYNOPSIS
  46 .In sys/types.h
  47 .In dirent.h
  48 .Ft int
  49 .Fn scandir "const char *dirname" "struct dirent ***namelist" "int \\*(lp*select\\*(rp\\*(lpstruct dirent *\\*(rp" "int \\*(lp*compar\\*(rp\\*(lpconst void *, const void *\\*(rp"
  50 .Ft int
  51 .Fn alphasort "const void *d1" "const void *d2"
  52 #ifdef UNIFDEF_BLOCKS
  53 .Ft int
  54 .Fn scandir_b "const char *dirname" "struct dirent ***namelist" "int \\*(lp^select\\*(rp\\*(lpstruct dirent *\\*(rp" "int \\*(lp^compar\\*(rp\\*(lpconst void *, const void *\\*(rp"
  55 #endif
  56 .Sh DESCRIPTION
  57 The
  58 .Fn scandir
  59 function
  60 reads the directory
  61 .Fa dirname
  62 and builds an array of pointers to directory
  63 entries using
  64 .Xr malloc 3 .
  65 It returns the number of entries in the array.
  66 A pointer to the array of directory entries is stored in the location
  67 referenced by
  68 .Fa namelist .
  69 .Pp
  70 The
  71 .Fa select
  72 argument is a pointer to a user supplied subroutine which is called by
  73 .Fn scandir
  74 to select which entries are to be included in the array.
  75 The select routine is passed a
  76 pointer to a directory entry and should return a non-zero
  77 value if the directory entry is to be included in the array.
  78 If
  79 .Fa select
  80 is null, then all the directory entries will be included.
  81 .Pp
  82 The
  83 .Fa compar
  84 argument is a pointer to a user supplied subroutine which is passed to
  85 .Xr qsort 3
  86 to sort the completed array.
  87 If this pointer is null, the array is not sorted.
  88 Note that from within the
  89 .Fa compar
  90 subroutine, the two arguments are of type
  91 .Ft const struct dirent ** ,
  92 so that a double-dereference is needed to access the fields in the
  93 .Ft dirent
  94 structure.
  95 .Pp
  96 The
  97 .Fn alphasort
  98 function
  99 is a routine which can be used for the
 100 .Fa compar
 101 argument to sort the array alphabetically.
 102 .Pp
 103 The memory allocated for the array can be deallocated with
 104 .Xr free 3 ,
 105 by freeing each pointer in the array and then the array itself.
 106 #ifdef UNIFDEF_BLOCKS
 107 .Pp
 108 The
 109 .Fn scandir_b
 110 function works the same way as the
 111 .Fn scandir
 112 function, except that
 113 .Fa select
 114 and
 115 .Fa compar
 116 are blocks instead of subroutines.
 117 #endif
 118 .Sh DIAGNOSTICS
 119 Returns \-1 if the directory cannot be opened for reading or if
 120 .Xr malloc 3
 121 cannot allocate enough memory to hold all the data structures.
 122 .Sh SEE ALSO
 123 .Xr directory 3 ,
 124 .Xr malloc 3 ,
 125 .Xr qsort 3 ,
 126 .Xr dir 5
 127 .Sh HISTORY
 128 The
 129 .Fn scandir
 130 and
 131 .Fn alphasort
 132 functions appeared in
 133 .Bx 4.2 .
 134 #ifdef UNIFDEF_BLOCKS
 135 The
 136 .Fn scandir_b
 137 function appeared in Mac OS X 10.6.
 138 #endif