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