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: src/lib/libc/gen/glob.3,v 1.32 2007/01/09 00:27:54 imp Exp $
  32 .\" $DragonFly: src/lib/libc/gen/glob.3,v 1.5 2007/06/30 19:03:52 swildner Exp $
  33 .\"
  34 .Dd December 6, 2005
  35 .Dt GLOB 3
  36 .Os
  37 .Sh NAME
  38 .Nm glob ,
  39 .Nm globfree
  40 .Nd generate pathnames matching a pattern
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In glob.h
  45 .Ft int
  46 .Fn glob "const char *pattern" "int flags" "int (*errfunc)(const char *, int)" "glob_t *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         size_t 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 .Tn ASCII
 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 .It Dv GLOB_PERIOD
 271 Allow matching of pathnames which start with a period.
 272 .El
 273 .Pp
 274 If, during the search, a directory is encountered that cannot be opened
 275 or read and
 276 .Fa errfunc
 277 is
 278 .Pf non- Dv NULL ,
 279 .Fn glob
 280 calls
 281 .Fa \*(lp*errfunc\*(rp Ns ( Fa path , errno ) .
 282 This may be unintuitive: a pattern like
 283 .Ql */Makefile
 284 will try to
 285 .Xr stat 2
 286 .Ql foo/Makefile
 287 even if
 288 .Ql foo
 289 is not a directory, resulting in a
 290 call to
 291 .Fa errfunc .
 292 The error routine can suppress this action by testing for
 293 .Er ENOENT
 294 and
 295 .Er ENOTDIR ;
 296 however, the
 297 .Dv GLOB_ERR
 298 flag will still cause an immediate
 299 return when this happens.
 300 .Pp
 301 If
 302 .Fa errfunc
 303 returns non-zero,
 304 .Fn glob
 305 stops the scan and returns
 306 .Dv GLOB_ABORTED
 307 after setting
 308 .Fa gl_pathc
 309 and
 310 .Fa gl_pathv
 311 to reflect any paths already matched.
 312 This also happens if an error is encountered and
 313 .Dv GLOB_ERR
 314 is set in
 315 .Fa flags ,
 316 regardless of the return value of
 317 .Fa errfunc ,
 318 if called.
 319 If
 320 .Dv GLOB_ERR
 321 is not set and either
 322 .Fa errfunc
 323 is
 324 .Dv NULL
 325 or
 326 .Fa errfunc
 327 returns zero, the error is ignored.
 328 .Pp
 329 The
 330 .Fn globfree
 331 function frees any space associated with
 332 .Fa pglob
 333 from a previous call(s) to
 334 .Fn glob .
 335 .Sh RETURN VALUES
 336 On successful completion,
 337 .Fn glob
 338 returns zero.
 339 In addition the fields of
 340 .Fa pglob
 341 contain the values described below:
 342 .Bl -tag -width GLOB_NOCHECK
 343 .It Fa gl_pathc
 344 contains the total number of matched pathnames so far.
 345 This includes other matches from previous invocations of
 346 .Fn glob
 347 if
 348 .Dv GLOB_APPEND
 349 was specified.
 350 .It Fa gl_matchc
 351 contains the number of matched pathnames in the current invocation of
 352 .Fn glob .
 353 .It Fa gl_flags
 354 contains a copy of the
 355 .Fa flags
 356 argument with the bit
 357 .Dv GLOB_MAGCHAR
 358 set if
 359 .Fa pattern
 360 contained any of the special characters ``*'', ``?'' or ``['', cleared
 361 if not.
 362 .It Fa gl_pathv
 363 contains a pointer to a
 364 .Dv NULL Ns -terminated
 365 list of matched pathnames.
 366 However, if
 367 .Fa gl_pathc
 368 is zero, the contents of
 369 .Fa gl_pathv
 370 are undefined.
 371 .El
 372 .Pp
 373 If
 374 .Fn glob
 375 terminates due to an error, it sets
 376 .Va errno
 377 and returns one of the
 378 following non-zero constants, which are defined in the include file
 379 .In glob.h :
 380 .Bl -tag -width 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 .Fa \*(lp*errfunc\*(rp\*(lp\*(rp
 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 regexp 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 may fail and set
 467 .Va errno
 468 for any of the errors specified for the 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 .