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 .\" 4. 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 .\" $FreeBSD: src/lib/libc/gen/glob.3,v 1.32 2007/01/09 00:27:54 imp Exp $
  32 .\"
  33 .Dd May 20, 2008
  34 .Dt GLOB 3
  35 .Os
  36 .Sh NAME
  37 .Nm glob ,
  38 #ifdef UNIFDEF_BLOCKS
  39 .Nm glob_b ,
  40 #endif
  41 .Nm globfree
  42 .Nd generate pathnames matching a pattern
  43 .Sh SYNOPSIS
  44 .In glob.h
  45 .Ft int
  46 .Fo glob
  47 .Fa "const char *restrict pattern"
  48 .Fa "int flags"
  49 .Fa "int (*errfunc)(const char *epath, int errno)"
  50 .Fa "glob_t *restrict pglob"
  51 .Fc
  52 #ifdef UNIFDEF_BLOCKS
  53 .Ft int
  54 .Fo glob_b
  55 .Fa "const char *restrict pattern"
  56 .Fa "int flags"
  57 .Fa "int (^errblk)(const char *epath, int errno)"
  58 .Fa "glob_t *restrict pglob"
  59 .Fc
  60 #endif
  61 .Ft void
  62 .Fo globfree
  63 .Fa "glob_t *pglob"
  64 .Fc
  65 .Sh DESCRIPTION
  66 The
  67 .Fn glob
  68 function
  69 is a pathname generator that implements the rules for file name pattern
  70 matching used by the shell.
  71 .Pp
  72 The include file
  73 .In glob.h
  74 defines the structure type
  75 .Fa glob_t ,
  76 which contains at least the following fields:
  77 .Bd -literal
  78 typedef struct {
  79         size_t gl_pathc;        /* count of total paths so far */
  80         int gl_matchc;          /* count of paths matching pattern */
  81         size_t gl_offs;         /* reserved at beginning of gl_pathv */
  82         int gl_flags;           /* returned flags */
  83         char **gl_pathv;        /* list of paths matching pattern */
  84 } glob_t;
  85 .Ed
  86 .Pp
  87 The argument
  88 .Fa pattern
  89 is a pointer to a pathname pattern to be expanded.
  90 The
  91 .Fn glob
  92 argument
  93 matches all accessible pathnames against the pattern and creates
  94 a list of the pathnames that match.
  95 In order to have access to a pathname,
  96 .Fn glob
  97 requires search permission on every component of a path except the last
  98 and read permission on each directory of any filename component of
  99 .Fa pattern
 100 that contains any of the special characters
 101 .Ql * ,
 102 .Ql ?\&
 103 or
 104 .Ql \&[ .
 105 .Pp
 106 The
 107 .Fn glob
 108 argument
 109 stores the number of matched pathnames into the
 110 .Fa gl_pathc
 111 field, and a pointer to a list of pointers to pathnames into the
 112 .Fa gl_pathv
 113 field.
 114 The first pointer after the last pathname is
 115 .Dv NULL .
 116 If the pattern does not match any pathnames, the returned number of
 117 matched paths is set to zero.
 118 .Pp
 119 It is the caller's responsibility to create the structure pointed to by
 120 .Fa pglob .
 121 The
 122 .Fn glob
 123 function allocates other space as needed, including the memory pointed
 124 to by
 125 .Fa gl_pathv .
 126 .Pp
 127 The argument
 128 .Fa flags
 129 is used to modify the behavior of
 130 .Fn glob .
 131 The value of
 132 .Fa flags
 133 is the bitwise inclusive
 134 .Tn OR
 135 of any of the following
 136 values defined in
 137 .In glob.h :
 138 .Bl -tag -width GLOB_ALTDIRFUNC
 139 .It Dv GLOB_APPEND
 140 Append pathnames generated to the ones from a previous call (or calls)
 141 to
 142 .Fn glob .
 143 The value of
 144 .Fa gl_pathc
 145 will be the total matches found by this call and the previous call(s).
 146 The pathnames are appended to, not merged with the pathnames returned by
 147 the previous call(s).
 148 Between calls, the caller must not change the setting of the
 149 .Dv GLOB_DOOFFS
 150 flag, nor change the value of
 151 .Fa gl_offs
 152 when
 153 .Dv GLOB_DOOFFS
 154 is set, nor (obviously) call
 155 .Fn globfree
 156 for
 157 .Fa pglob .
 158 .It Dv GLOB_DOOFFS
 159 Make use of the
 160 .Fa gl_offs
 161 field.
 162 If this flag is set,
 163 .Fa gl_offs
 164 is used to specify how many
 165 .Dv NULL
 166 pointers to prepend to the beginning
 167 of the
 168 .Fa gl_pathv
 169 field.
 170 In other words,
 171 .Fa gl_pathv
 172 will point to
 173 .Fa gl_offs
 174 .Dv NULL
 175 pointers,
 176 followed by
 177 .Fa gl_pathc
 178 pathname pointers, followed by a
 179 .Dv NULL
 180 pointer.
 181 .It Dv GLOB_ERR
 182 Causes
 183 .Fn glob
 184 to return when it encounters a directory that it cannot open or read.
 185 Ordinarily,
 186 .Fn glob
 187 continues to find matches.
 188 .It Dv GLOB_MARK
 189 Each pathname that is a directory that matches
 190 .Fa pattern
 191 has a slash
 192 appended.
 193 .It Dv GLOB_NOCHECK
 194 If
 195 .Fa pattern
 196 does not match any pathname, then
 197 .Fn glob
 198 returns a list
 199 consisting of only
 200 .Fa pattern ,
 201 with the number of total pathnames set to 1, and the number of matched
 202 pathnames set to 0.
 203 The effect of backslash escaping is present in the pattern returned.
 204 .It Dv GLOB_NOESCAPE
 205 By default, a backslash
 206 .Pq Ql \e
 207 character is used to escape the following character in the pattern,
 208 avoiding any special interpretation of the character.
 209 If
 210 .Dv GLOB_NOESCAPE
 211 is set, backslash escaping is disabled.
 212 .It Dv GLOB_NOSORT
 213 By default, the pathnames are sorted in ascending
 214 .Tn ASCII
 215 order;
 216 this flag prevents that sorting (speeding up
 217 .Fn glob ) .
 218 .El
 219 .Pp
 220 The following values may also be included in
 221 .Fa flags ,
 222 however, they are non-standard extensions to
 223 .St -p1003.2 .
 224 .Bl -tag -width GLOB_ALTDIRFUNC
 225 .It Dv GLOB_ALTDIRFUNC
 226 The following additional fields in the pglob structure have been
 227 initialized with alternate functions for glob to use to open, read,
 228 and close directories and to get stat information on names found
 229 in those directories.
 230 .Bd -literal
 231 void *(*gl_opendir)(const char * name);
 232 struct dirent *(*gl_readdir)(void *);
 233 void (*gl_closedir)(void *);
 234 int (*gl_lstat)(const char *name, struct stat *st);
 235 int (*gl_stat)(const char *name, struct stat *st);
 236 .Ed
 237 .Pp
 238 This extension is provided to allow programs such as
 239 .Xr restore 8
 240 to provide globbing from directories stored on tape.
 241 .It Dv GLOB_BRACE
 242 Pre-process the pattern string to expand
 243 .Ql {pat,pat,...}
 244 strings like
 245 .Xr csh 1 .
 246 The pattern
 247 .Ql {}
 248 is left unexpanded for historical reasons (and
 249 .Xr csh 1
 250 does the same thing to
 251 ease typing
 252 of
 253 .Xr find 1
 254 patterns).
 255 .It Dv GLOB_MAGCHAR
 256 Set by the
 257 .Fn glob
 258 function if the pattern included globbing characters.
 259 See the description of the usage of the
 260 .Fa gl_matchc
 261 structure member for more details.
 262 .It Dv GLOB_NOMAGIC
 263 Is the same as
 264 .Dv GLOB_NOCHECK
 265 but it only appends the
 266 .Fa pattern
 267 if it does not contain any of the special characters ``*'', ``?'' or ``[''.
 268 .Dv GLOB_NOMAGIC
 269 is provided to simplify implementing the historic
 270 .Xr csh 1
 271 globbing behavior and should probably not be used anywhere else.
 272 .It Dv GLOB_TILDE
 273 Expand patterns that start with
 274 .Ql ~
 275 to user name home directories.
 276 .It Dv GLOB_LIMIT
 277 Limit the total number of returned pathnames to the value provided in
 278 .Fa gl_matchc
 279 (default
 280 .Dv ARG_MAX ) .
 281 This option should be set for programs
 282 that can be coerced into a denial of service attack
 283 via patterns that expand to a very large number of matches,
 284 such as a long string of
 285 .Ql */../*/.. .
 286 .El
 287 .Pp
 288 If, during the search, a directory is encountered that cannot be opened
 289 or read and
 290 .Fa errfunc
 291 is
 292 .Pf non- Dv NULL ,
 293 .Fn glob
 294 calls
 295 .Fa \*(lp*errfunc\*(rp Ns ( Fa path , errno ) .
 296 This may be unintuitive: a pattern like
 297 .Ql */Makefile
 298 will try to
 299 .Xr stat 2
 300 .Ql foo/Makefile
 301 even if
 302 .Ql foo
 303 is not a directory, resulting in a
 304 call to
 305 .Fa errfunc .
 306 The error routine can suppress this action by testing for
 307 .Er ENOENT
 308 and
 309 .Er ENOTDIR ;
 310 however, the
 311 .Dv GLOB_ERR
 312 flag will still cause an immediate
 313 return when this happens.
 314 .Pp
 315 If
 316 .Fa errfunc
 317 returns non-zero,
 318 .Fn glob
 319 stops the scan and returns
 320 .Dv GLOB_ABORTED
 321 after setting
 322 .Fa gl_pathc
 323 and
 324 .Fa gl_pathv
 325 to reflect any paths already matched.
 326 This also happens if an error is encountered and
 327 .Dv GLOB_ERR
 328 is set in
 329 .Fa flags ,
 330 regardless of the return value of
 331 .Fa errfunc ,
 332 if called.
 333 If
 334 .Dv GLOB_ERR
 335 is not set and either
 336 .Fa errfunc
 337 is
 338 .Dv NULL
 339 or
 340 .Fa errfunc
 341 returns zero, the error is ignored.
 342 #ifdef UNIFDEF_BLOCKS
 343 .Pp
 344 The
 345 .Fn glob_b
 346 function is like
 347 .Fn glob
 348 except that the error callback is a block pointer instead of a function
 349 pointer.
 350 #endif
 351 .Pp
 352 The
 353 .Fn globfree
 354 function frees any space associated with
 355 .Fa pglob
 356 from a previous call(s) to
 357 #ifdef UNIFDEF_BLOCKS
 358 .Fn glob
 359 or
 360 .Fn glob_b .
 361 #else
 362 .Fn glob .
 363 #endif
 364 .Sh RETURN VALUES
 365 On successful completion,
 366 .Fn glob
 367 #ifdef UNIFDEF_BLOCKS
 368 and
 369 .Fn glob_b
 370 return zero.
 371 #else
 372 returns zero.
 373 #endif
 374 In addition, the fields of
 375 .Fa pglob
 376 contain the values described below:
 377 .Bl -tag -width GLOB_NOCHECK
 378 .It Fa gl_pathc
 379 contains the total number of matched pathnames so far.
 380 This includes other matches from previous invocations of
 381 .Fn glob
 382 #ifdef UNIFDEF_BLOCKS
 383 or
 384 .Fn glob_b
 385 #endif
 386 if
 387 .Dv GLOB_APPEND
 388 was specified.
 389 .It Fa gl_matchc
 390 contains the number of matched pathnames in the current invocation of
 391 #ifdef UNIFDEF_BLOCKS
 392 .Fn glob
 393 or
 394 .Fn glob_b .
 395 #else
 396 .Fn glob .
 397 #endif
 398 .It Fa gl_flags
 399 contains a copy of the
 400 .Fa flags
 401 argument with the bit
 402 .Dv GLOB_MAGCHAR
 403 set if
 404 .Fa pattern
 405 contained any of the special characters ``*'', ``?'' or ``['', cleared
 406 if not.
 407 .It Fa gl_pathv
 408 contains a pointer to a
 409 .Dv NULL Ns -terminated
 410 list of matched pathnames.
 411 However, if
 412 .Fa gl_pathc
 413 is zero, the contents of
 414 .Fa gl_pathv
 415 are undefined.
 416 .El
 417 .Pp
 418 If
 419 .Fn glob
 420 #ifdef UNIFDEF_BLOCKS
 421 or
 422 .Fn glob_b
 423 #endif
 424 terminates due to an error, it sets errno and returns one of the
 425 following non-zero constants, which are defined in the include
 426 file
 427 .In glob.h :
 428 .Bl -tag -width GLOB_NOCHECK
 429 .It Dv GLOB_NOSPACE
 430 An attempt to allocate memory failed, or if
 431 .Fa errno
 432 was 0
 433 .Dv GLOB_LIMIT
 434 was specified in the flags and
 435 .Fa pglob\->gl_matchc
 436 or more patterns were matched.
 437 .It Dv GLOB_ABORTED
 438 The scan was stopped because an error was encountered and either
 439 .Dv GLOB_ERR
 440 was set or
 441 .Fa \*(lp*errfunc\*(rp\*(lp\*(rp
 442 returned non-zero.
 443 .It Dv GLOB_NOMATCH
 444 The pattern did not match a pathname and
 445 .Dv GLOB_NOCHECK
 446 was not set.
 447 .El
 448 .Pp
 449 The arguments
 450 .Fa pglob\->gl_pathc
 451 and
 452 .Fa pglob\->gl_pathv
 453 are still set as specified above.
 454 .Sh EXAMPLES
 455 A rough equivalent of
 456 .Ql "ls -l *.c *.h"
 457 can be obtained with the
 458 following code:
 459 .Bd -literal -offset indent
 460 glob_t g;
 461
 462 g.gl_offs = 2;
 463 glob("*.c", GLOB_DOOFFS, NULL, &g);
 464 glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
 465 g.gl_pathv[0] = "ls";
 466 g.gl_pathv[1] = "-l";
 467 execvp("ls", g.gl_pathv);
 468 .Ed
 469 .Sh CAVEATS
 470 The
 471 .Fn glob
 472 #ifdef UNIFDEF_BLOCKS
 473 and
 474 .Fn glob_b
 475 functions
 476 #else
 477 function
 478 #endif
 479 will not match filenames that begin with a period
 480 unless this is specifically requested (e.g., by ".*").
 481 .Sh SEE ALSO
 482 .Xr sh 1 ,
 483 .Xr fnmatch 3 ,
 484 .Xr regexp 3
 485 .Sh STANDARDS
 486 The current implementation of the
 487 .Fn glob
 488 function
 489 .Em does not
 490 conform to
 491 .St -p1003.2 .
 492 Collating symbol expressions, equivalence class expressions and
 493 character class expressions are not supported.
 494 .Pp
 495 The flags
 496 .Dv GLOB_ALTDIRFUNC ,
 497 .Dv GLOB_BRACE ,
 498 .Dv GLOB_LIMIT ,
 499 .Dv GLOB_MAGCHAR ,
 500 .Dv GLOB_NOMAGIC ,
 501 and
 502 .Dv GLOB_TILDE ,
 503 and the fields
 504 .Fa gl_matchc
 505 and
 506 .Fa gl_flags
 507 are extensions to the
 508 .Tn POSIX
 509 standard and
 510 should not be used by applications striving for strict
 511 conformance.
 512 .Sh HISTORY
 513 The
 514 .Fn glob
 515 and
 516 .Fn globfree
 517 functions first appeared in
 518 .Bx 4.4 .
 519 #ifdef UNIFDEF_BLOCKS
 520 The
 521 .Fn glob_b
 522 function first appeared in Mac OS X 10.6.
 523 #endif
 524 .Sh BUGS
 525 Patterns longer than
 526 .Dv MAXPATHLEN
 527 may cause unchecked errors.
 528 .Pp
 529 The
 530 .Fn glob
 531 #ifdef UNIFDEF_BLOCKS
 532 and
 533 .Fn glob_b
 534 functions
 535 #else
 536 function
 537 #endif
 538 may fail and set errno for any of the errors specified for the
 539 library routines
 540 .Xr stat 2 ,
 541 .Xr closedir 3 ,
 542 .Xr opendir 3 ,
 543 .Xr readdir 3 ,
 544 .Xr malloc 3 ,
 545 and
 546 .Xr free 3 .