1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .Dd "Jul 22, 2014"
   7 .Dt SCANDIR 3C
   8 .Os
   9 .Sh NAME
  10 .Nm scandir ,
  11 .Nm alphasort
  12 .Nd scan a directory
  13 .Sh SYNOPSIS
  14 .In dirent.h
  15 .
  16 .Ft int
  17 .Fo scandir
  18 .Fa "const char *dirname"
  19 .Fa "struct dirent ***namelist"
  20 .Fa "int \*(lp*select\*(rp\*(lpconst struct dirent *\*(rp"
  21 .Fa "int \*(lp*dcomp\*(rp\*(lpconst struct dirent  **, const struct dirent **\*(rp"
  22 .Fc
  23 .
  24 .Ft int
  25 .Fn alphasort "const struct dirent **d1" "const struct dirent **d2"
  26 .
  27 .Sh DESCRIPTION
  28 The
  29 .Fn scandir
  30 function reads the directory
  31 .Fa dirname
  32 using
  33 .Xr readdir 3C
  34 and builds an array of pointers to directory entries using
  35 .Xr malloc 3C .
  36 The
  37 .Fa namelist
  38 argument is a pointer to an array of
  39 structure pointers. The
  40 .Fa select
  41 argument is a pointer to a routine that is
  42 called with a pointer to a directory entry and returns a non-zero value if the
  43 directory entry is included in the array. If this pointer is
  44 .Dv NULL ,
  45 then
  46 all the directory entries are included. The
  47 .Fa dcomp
  48 argument is a pointer
  49 to a routine that is passed to
  50 .Xr qsort 3C ,
  51 which sorts the completed array. If this pointer is
  52 .Dv NULL ,
  53 the array is not sorted.
  54 .Lp
  55 The
  56 .Fn alphasort
  57 function can be used as the
  58 .Fn dcomp
  59 function parameter for the
  60 .Fn scandir
  61 function to sort the directory entries into
  62 alphabetical order, as if by the
  63 .Xr strcoll 3C
  64 function. Its arguments are
  65 the two directory entries to compare.
  66 .Sh RETURN VALUES
  67 The
  68 .Fn scandir
  69 function returns the number of entries in the array and a
  70 pointer to the array through the
  71 .Fa namelist
  72 argument. When an error is
  73 encountered,
  74 .Fn scandir
  75 returns -1 and
  76 .Va errno
  77 is set to indicate the error.
  78 .Lp
  79 The
  80 .Fn alphasort
  81 function returns an integer greater than, equal to, or
  82 less than 0 if the directory entry name pointed to by
  83 .Fa d1
  84 is greater than, equal to, or less than the directory entry name pointed to by
  85 .Fa d2
  86 when
  87 both are interpreted as appropriate to the current locale. There is no return
  88 value reserved to indicate an error.
  89 .Sh ERRORS
  90 The
  91 .Fn scandir
  92 function will fail if:
  93 .Bl -tag -width Er
  94 .It Er EOVERFLOW
  95 The number of directory entries exceeds the number that can be represented by
  96 an
  97 .Vt int .
  98 .El
  99 .Sh USAGE
 100 The
 101 .Fn scandir
 102 and
 103 .Fn alphasort
 104 functions have transitional interfaces for 64-bit file offsets. See
 105 .Xr lf64 5 .
 106 .Sh INTERFACE STABILITY
 107 .Sy Standard .
 108 .Sh MT-LEVEL
 109 The
 110 .Fn scandir
 111 function is
 112 .Sy Unsafe .
 113 The
 114 .Fn alphasort
 115 function is
 116 .Sy Safe .
 117 .Sh SEE ALSO
 118 .Xr malloc 3C ,
 119 .Xr qsort 3C ,
 120 .Xr readdir 3C ,
 121 .Xr strcoll 3C ,
 122 .Xr lf64 5 ,
 123 .Xr standards 5
 124 .Sh STANDARDS
 125 The
 126 .Fn alphasort
 127 and
 128 .Fn scandir
 129 functions were introduced in
 130 .St -p1003.1-2008 .