lib/libc/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.3.2.5 2003/03/15 15:11:05 trhodes Exp $
  34 .\"
  35 .Dd November 4, 2010
  36 .Dt SCANDIR 3
  37 .Os
  38 .Sh NAME
  39 .Nm scandir ,
  40 .Nm alphasort
  41 .Nd scan a directory
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In sys/types.h
  46 .In dirent.h
  47 .Ft int
  48 .Fn scandir "const char *dirname" "struct dirent ***namelist" "int \\*(lp*select\\*(rp\\*(lpconst struct dirent *\\*(rp" "int \\*(lp*compar\\*(rp\\*(lpconst struct dirent **, const struct dirent **\\*(rp"
  49 .Ft int
  50 .Fn alphasort "const struct dirent **d1" "const struct dirent **d2"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn scandir
  54 function
  55 reads the directory
  56 .Fa dirname
  57 and builds an array of pointers to directory
  58 entries using
  59 .Xr malloc 3 .
  60 It returns the number of entries in the array.
  61 A pointer to the array of directory entries is stored in the location
  62 referenced by
  63 .Fa namelist .
  64 .Pp
  65 The
  66 .Fa select
  67 argument is a pointer to a user supplied subroutine which is called by
  68 .Fn scandir
  69 to select which entries are to be included in the array.
  70 The select routine is passed a
  71 pointer to a directory entry and should return a non-zero
  72 value if the directory entry is to be included in the array.
  73 If
  74 .Fa select
  75 is null, then all the directory entries will be included.
  76 .Pp
  77 The
  78 .Fa compar
  79 argument is a pointer to a user supplied subroutine which is passed to
  80 .Xr qsort 3
  81 to sort the completed array.
  82 If this pointer is null, the array is not sorted.
  83 .Pp
  84 The
  85 .Fn alphasort
  86 function
  87 is a routine which can be used for the
  88 .Fa compar
  89 argument to sort the array alphabetically.
  90 .Pp
  91 The memory allocated for the array can be deallocated with
  92 .Xr free 3 ,
  93 by freeing each pointer in the array and then the array itself.
  94 .Sh DIAGNOSTICS
  95 Returns \-1 if the directory cannot be opened for reading or if
  96 .Xr malloc 3
  97 cannot allocate enough memory to hold all the data structures.
  98 .Sh SEE ALSO
  99 .Xr directory 3 ,
 100 .Xr malloc 3 ,
 101 .Xr qsort 3 ,
 102 .Xr dir 5
 103 .Sh HISTORY
 104 The
 105 .Fn scandir
 106 and
 107 .Fn alphasort
 108 functions appeared in
 109 .Bx 4.2 .