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