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