lib/libc/gen/glob.3

   1 .\" Copyright (c) 1989, 1991, 1993, 1994
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Guido van Rossum.
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)glob.3      8.3 (Berkeley) 4/16/94
  31 .\"
  32 .Dd December 20, 2011
  33 .Dt GLOB 3
  34 .Os
  35 .Sh NAME
  36 .Nm glob ,
  37 .Nm globfree
  38 .Nd generate pathnames matching a pattern
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In glob.h
  43 .Ft int
  44 .Fn glob "const char * restrict pattern" "int flags" "int (*errfunc)(const char *, int)" "glob_t * restrict pglob"
  45 .Ft void
  46 .Fn globfree "glob_t *pglob"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn glob
  50 function
  51 is a pathname generator that implements the rules for file name pattern
  52 matching used by the shell.
  53 .Pp
  54 The include file
  55 .In glob.h
  56 defines the structure type
  57 .Fa glob_t ,
  58 which contains at least the following fields:
  59 .Bd -literal
  60 typedef struct {
  61         size_t gl_pathc;        /* count of total paths so far */
  62         size_t gl_matchc;       /* count of paths matching pattern */
  63         size_t gl_offs;         /* reserved at beginning of gl_pathv */
  64         int gl_flags;           /* returned flags */
  65         char **gl_pathv;        /* list of paths matching pattern */
  66 } glob_t;
  67 .Ed
  68 .Pp
  69 The argument
  70 .Fa pattern
  71 is a pointer to a pathname pattern to be expanded.
  72 The
  73 .Fn glob
  74 argument
  75 matches all accessible pathnames against the pattern and creates
  76 a list of the pathnames that match.
  77 In order to have access to a pathname,
  78 .Fn glob
  79 requires search permission on every component of a path except the last
  80 and read permission on each directory of any filename component of
  81 .Fa pattern
  82 that contains any of the special characters
  83 .Ql * ,
  84 .Ql ?\&
  85 or
  86 .Ql \&[ .
  87 .Pp
  88 The
  89 .Fn glob
  90 argument
  91 stores the number of matched pathnames into the
  92 .Fa gl_pathc
  93 field, and a pointer to a list of pointers to pathnames into the
  94 .Fa gl_pathv
  95 field.
  96 The first pointer after the last pathname is
  97 .Dv NULL .
  98 If the pattern does not match any pathnames, the returned number of
  99 matched paths is set to zero.
 100 .Pp
 101 It is the caller's responsibility to create the structure pointed to by
 102 .Fa pglob .
 103 The
 104 .Fn glob
 105 function allocates other space as needed, including the memory pointed
 106 to by
 107 .Fa gl_pathv .
 108 .Pp
 109 The argument
 110 .Fa flags
 111 is used to modify the behavior of
 112 .Fn glob .
 113 The value of
 114 .Fa flags
 115 is the bitwise inclusive
 116 .Tn OR
 117 of any of the following
 118 values defined in
 119 .In glob.h :
 120 .Bl -tag -width GLOB_ALTDIRFUNC
 121 .It Dv GLOB_APPEND
 122 Append pathnames generated to the ones from a previous call (or calls)
 123 to
 124 .Fn glob .
 125 The value of
 126 .Fa gl_pathc
 127 will be the total matches found by this call and the previous call(s).
 128 The pathnames are appended to, not merged with the pathnames returned by
 129 the previous call(s).
 130 Between calls, the caller must not change the setting of the
 131 .Dv GLOB_DOOFFS
 132 flag, nor change the value of
 133 .Fa gl_offs
 134 when
 135 .Dv GLOB_DOOFFS
 136 is set, nor (obviously) call
 137 .Fn globfree
 138 for
 139 .Fa pglob .
 140 .It Dv GLOB_DOOFFS
 141 Make use of the
 142 .Fa gl_offs
 143 field.
 144 If this flag is set,
 145 .Fa gl_offs
 146 is used to specify how many
 147 .Dv NULL
 148 pointers to prepend to the beginning
 149 of the
 150 .Fa gl_pathv
 151 field.
 152 In other words,
 153 .Fa gl_pathv
 154 will point to
 155 .Fa gl_offs
 156 .Dv NULL
 157 pointers,
 158 followed by
 159 .Fa gl_pathc
 160 pathname pointers, followed by a
 161 .Dv NULL
 162 pointer.
 163 .It Dv GLOB_ERR
 164 Causes
 165 .Fn glob
 166 to return when it encounters a directory that it cannot open or read.
 167 Ordinarily,
 168 .Fn glob
 169 continues to find matches.
 170 .It Dv GLOB_MARK
 171 Each pathname that is a directory that matches
 172 .Fa pattern
 173 has a slash
 174 appended.
 175 .It Dv GLOB_NOCHECK
 176 If
 177 .Fa pattern
 178 does not match any pathname, then
 179 .Fn glob
 180 returns a list
 181 consisting of only
 182 .Fa pattern ,
 183 with the number of total pathnames set to 1, and the number of matched
 184 pathnames set to 0.
 185 The effect of backslash escaping is present in the pattern returned.
 186 .It Dv GLOB_NOESCAPE
 187 By default, a backslash
 188 .Pq Ql \e
 189 character is used to escape the following character in the pattern,
 190 avoiding any special interpretation of the character.
 191 If
 192 .Dv GLOB_NOESCAPE
 193 is set, backslash escaping is disabled.
 194 .It Dv GLOB_NOSORT
 195 By default, the pathnames are sorted in ascending
 196 collation
 197 order;
 198 this flag prevents that sorting (speeding up
 199 .Fn glob ) .
 200 .El
 201 .Pp
 202 The following values may also be included in
 203 .Fa flags ,
 204 however, they are non-standard extensions to
 205 .St -p1003.2 .
 206 .Bl -tag -width GLOB_ALTDIRFUNC
 207 .It Dv GLOB_ALTDIRFUNC
 208 The following additional fields in the pglob structure have been
 209 initialized with alternate functions for glob to use to open, read,
 210 and close directories and to get stat information on names found
 211 in those directories.
 212 .Bd -literal
 213 void *(*gl_opendir)(const char * name);
 214 struct dirent *(*gl_readdir)(void *);
 215 void (*gl_closedir)(void *);
 216 int (*gl_lstat)(const char *name, struct stat *st);
 217 int (*gl_stat)(const char *name, struct stat *st);
 218 .Ed
 219 .Pp
 220 This extension is provided to allow programs such as
 221 .Xr restore 8
 222 to provide globbing from directories stored on tape.
 223 .It Dv GLOB_BRACE
 224 Pre-process the pattern string to expand
 225 .Ql {pat,pat,...}
 226 strings like
 227 .Xr csh 1 .
 228 The pattern
 229 .Ql {}
 230 is left unexpanded for historical reasons (and
 231 .Xr csh 1
 232 does the same thing to
 233 ease typing
 234 of
 235 .Xr find 1
 236 patterns).
 237 .It Dv GLOB_MAGCHAR
 238 Set by the
 239 .Fn glob
 240 function if the pattern included globbing characters.
 241 See the description of the usage of the
 242 .Fa gl_matchc
 243 structure member for more details.
 244 .It Dv GLOB_NOMAGIC
 245 Is the same as
 246 .Dv GLOB_NOCHECK
 247 but it only appends the
 248 .Fa pattern
 249 if it does not contain any of the special characters ``*'', ``?'' or ``[''.
 250 .Dv GLOB_NOMAGIC
 251 is provided to simplify implementing the historic
 252 .Xr csh 1
 253 globbing behavior and should probably not be used anywhere else.
 254 .It Dv GLOB_TILDE
 255 Expand patterns that start with
 256 .Ql ~
 257 to user name home directories.
 258 .It Dv GLOB_LIMIT
 259 Limit the total number of returned pathnames to the value provided in
 260 .Fa gl_matchc
 261 (default
 262 .Dv ARG_MAX ) .
 263 This option should be set for programs
 264 that can be coerced into a denial of service attack
 265 via patterns that expand to a very large number of matches,
 266 such as a long string of
 267 .Ql */../*/.. .
 268 .El
 269 .Pp
 270 If, during the search, a directory is encountered that cannot be opened
 271 or read and
 272 .Fa errfunc
 273 is
 274 .Pf non- Dv NULL ,
 275 .Fn glob
 276 calls
 277 .Fa \*(lp*errfunc\*(rp Ns ( Fa path , errno ) ,
 278 however, the
 279 .Dv GLOB_ERR
 280 flag will cause an immediate
 281 return when this happens.
 282 .Pp
 283 If
 284 .Fa errfunc
 285 returns non-zero,
 286 .Fn glob
 287 stops the scan and returns
 288 .Dv GLOB_ABORTED
 289 after setting
 290 .Fa gl_pathc
 291 and
 292 .Fa gl_pathv
 293 to reflect any paths already matched.
 294 This also happens if an error is encountered and
 295 .Dv GLOB_ERR
 296 is set in
 297 .Fa flags ,
 298 regardless of the return value of
 299 .Fa errfunc ,
 300 if called.
 301 If
 302 .Dv GLOB_ERR
 303 is not set and either
 304 .Fa errfunc
 305 is
 306 .Dv NULL
 307 or
 308 .Fa errfunc
 309 returns zero, the error is ignored.
 310 .Pp
 311 The
 312 .Fn globfree
 313 function frees any space associated with
 314 .Fa pglob
 315 from a previous call(s) to
 316 .Fn glob .
 317 .Sh RETURN VALUES
 318 On successful completion,
 319 .Fn glob
 320 returns zero.
 321 In addition the fields of
 322 .Fa pglob
 323 contain the values described below:
 324 .Bl -tag -width GLOB_NOCHECK
 325 .It Fa gl_pathc
 326 contains the total number of matched pathnames so far.
 327 This includes other matches from previous invocations of
 328 .Fn glob
 329 if
 330 .Dv GLOB_APPEND
 331 was specified.
 332 .It Fa gl_matchc
 333 contains the number of matched pathnames in the current invocation of
 334 .Fn glob .
 335 .It Fa gl_flags
 336 contains a copy of the
 337 .Fa flags
 338 argument with the bit
 339 .Dv GLOB_MAGCHAR
 340 set if
 341 .Fa pattern
 342 contained any of the special characters ``*'', ``?'' or ``['', cleared
 343 if not.
 344 .It Fa gl_pathv
 345 contains a pointer to a
 346 .Dv NULL Ns -terminated
 347 list of matched pathnames.
 348 However, if
 349 .Fa gl_pathc
 350 is zero, the contents of
 351 .Fa gl_pathv
 352 are undefined.
 353 .El
 354 .Pp
 355 If
 356 .Fn glob
 357 terminates due to an error, it sets errno and returns one of the
 358 following non-zero constants, which are defined in the include
 359 file
 360 .In glob.h :
 361 .Bl -tag -width GLOB_NOCHECK
 362 .It Dv GLOB_NOSPACE
 363 An attempt to allocate memory failed, or if
 364 .Fa errno
 365 was E2BIG,
 366 .Dv GLOB_LIMIT
 367 was specified in the flags and
 368 .Fa pglob\->gl_matchc
 369 or more patterns were matched.
 370 .It Dv GLOB_ABORTED
 371 The scan was stopped because an error was encountered and either
 372 .Dv GLOB_ERR
 373 was set or
 374 .Fa \*(lp*errfunc\*(rp\*(lp\*(rp
 375 returned non-zero.
 376 .It Dv GLOB_NOMATCH
 377 The pattern did not match a pathname and
 378 .Dv GLOB_NOCHECK
 379 was not set.
 380 .El
 381 .Pp
 382 The arguments
 383 .Fa pglob\->gl_pathc
 384 and
 385 .Fa pglob\->gl_pathv
 386 are still set as specified above.
 387 .Sh EXAMPLES
 388 A rough equivalent of
 389 .Ql "ls -l *.c *.h"
 390 can be obtained with the
 391 following code:
 392 .Bd -literal -offset indent
 393 glob_t g;
 394
 395 g.gl_offs = 2;
 396 glob("*.c", GLOB_DOOFFS, NULL, &g);
 397 glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
 398 g.gl_pathv[0] = "ls";
 399 g.gl_pathv[1] = "-l";
 400 execvp("ls", g.gl_pathv);
 401 .Ed
 402 .Sh SEE ALSO
 403 .Xr sh 1 ,
 404 .Xr fnmatch 3 ,
 405 .Xr regex 3
 406 .Sh STANDARDS
 407 The current implementation of the
 408 .Fn glob
 409 function
 410 .Em does not
 411 conform to
 412 .St -p1003.2 .
 413 Collating symbol expressions, equivalence class expressions and
 414 character class expressions are not supported.
 415 .Pp
 416 The flags
 417 .Dv GLOB_ALTDIRFUNC ,
 418 .Dv GLOB_BRACE ,
 419 .Dv GLOB_LIMIT ,
 420 .Dv GLOB_MAGCHAR ,
 421 .Dv GLOB_NOMAGIC ,
 422 and
 423 .Dv GLOB_TILDE ,
 424 and the fields
 425 .Fa gl_matchc
 426 and
 427 .Fa gl_flags
 428 are extensions to the
 429 .Tn POSIX
 430 standard and
 431 should not be used by applications striving for strict
 432 conformance.
 433 .Sh HISTORY
 434 The
 435 .Fn glob
 436 and
 437 .Fn globfree
 438 functions first appeared in
 439 .Bx 4.4 .
 440 .Sh BUGS
 441 Patterns longer than
 442 .Dv MAXPATHLEN
 443 may cause unchecked errors.
 444 .Pp
 445 The
 446 .Fn glob
 447 argument
 448 may fail and set errno for any of the errors specified for the
 449 library routines
 450 .Xr stat 2 ,
 451 .Xr closedir 3 ,
 452 .Xr opendir 3 ,
 453 .Xr readdir 3 ,
 454 .Xr malloc 3 ,
 455 and
 456 .Xr free 3 .