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