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 however, the
 280 .Dv GLOB_ERR
 281 flag will cause an immediate
 282 return when this happens.
 283 .Pp
 284 If
 285 .Fa errfunc
 286 returns non-zero,
 287 .Fn glob
 288 stops the scan and returns
 289 .Dv GLOB_ABORTED
 290 after setting
 291 .Fa gl_pathc
 292 and
 293 .Fa gl_pathv
 294 to reflect any paths already matched.
 295 This also happens if an error is encountered and
 296 .Dv GLOB_ERR
 297 is set in
 298 .Fa flags ,
 299 regardless of the return value of
 300 .Fa errfunc ,
 301 if called.
 302 If
 303 .Dv GLOB_ERR
 304 is not set and either
 305 .Fa errfunc
 306 is
 307 .Dv NULL
 308 or
 309 .Fa errfunc
 310 returns zero, the error is ignored.
 311 .Pp
 312 The
 313 .Fn globfree
 314 function frees any space associated with
 315 .Fa pglob
 316 from a previous call(s) to
 317 .Fn glob .
 318 .Sh RETURN VALUES
 319 On successful completion,
 320 .Fn glob
 321 returns zero.
 322 In addition the fields of
 323 .Fa pglob
 324 contain the values described below:
 325 .Bl -tag -width GLOB_NOCHECK
 326 .It Fa gl_pathc
 327 contains the total number of matched pathnames so far.
 328 This includes other matches from previous invocations of
 329 .Fn glob
 330 if
 331 .Dv GLOB_APPEND
 332 was specified.
 333 .It Fa gl_matchc
 334 contains the number of matched pathnames in the current invocation of
 335 .Fn glob .
 336 .It Fa gl_flags
 337 contains a copy of the
 338 .Fa flags
 339 argument with the bit
 340 .Dv GLOB_MAGCHAR
 341 set if
 342 .Fa pattern
 343 contained any of the special characters ``*'', ``?'' or ``['', cleared
 344 if not.
 345 .It Fa gl_pathv
 346 contains a pointer to a
 347 .Dv NULL Ns -terminated
 348 list of matched pathnames.
 349 However, if
 350 .Fa gl_pathc
 351 is zero, the contents of
 352 .Fa gl_pathv
 353 are undefined.
 354 .El
 355 .Pp
 356 If
 357 .Fn glob
 358 terminates due to an error, it sets errno and returns one of the
 359 following non-zero constants, which are defined in the include
 360 file
 361 .In glob.h :
 362 .Bl -tag -width GLOB_NOCHECK
 363 .It Dv GLOB_NOSPACE
 364 An attempt to allocate memory failed, or if
 365 .Fa errno
 366 was E2BIG,
 367 .Dv GLOB_LIMIT
 368 was specified in the flags and
 369 .Fa pglob\->gl_matchc
 370 or more patterns were matched.
 371 .It Dv GLOB_ABORTED
 372 The scan was stopped because an error was encountered and either
 373 .Dv GLOB_ERR
 374 was set or
 375 .Fa \*(lp*errfunc\*(rp\*(lp\*(rp
 376 returned non-zero.
 377 .It Dv GLOB_NOMATCH
 378 The pattern did not match a pathname and
 379 .Dv GLOB_NOCHECK
 380 was not set.
 381 .El
 382 .Pp
 383 The arguments
 384 .Fa pglob\->gl_pathc
 385 and
 386 .Fa pglob\->gl_pathv
 387 are still set as specified above.
 388 .Sh EXAMPLES
 389 A rough equivalent of
 390 .Ql "ls -l *.c *.h"
 391 can be obtained with the
 392 following code:
 393 .Bd -literal -offset indent
 394 glob_t g;
 395
 396 g.gl_offs = 2;
 397 glob("*.c", GLOB_DOOFFS, NULL, &g);
 398 glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
 399 g.gl_pathv[0] = "ls";
 400 g.gl_pathv[1] = "-l";
 401 execvp("ls", g.gl_pathv);
 402 .Ed
 403 .Sh SEE ALSO
 404 .Xr sh 1 ,
 405 .Xr fnmatch 3 ,
 406 .Xr regex 3
 407 .Sh STANDARDS
 408 The current implementation of the
 409 .Fn glob
 410 function
 411 .Em does not
 412 conform to
 413 .St -p1003.2 .
 414 Collating symbol expressions, equivalence class expressions and
 415 character class expressions are not supported.
 416 .Pp
 417 The flags
 418 .Dv GLOB_ALTDIRFUNC ,
 419 .Dv GLOB_BRACE ,
 420 .Dv GLOB_LIMIT ,
 421 .Dv GLOB_MAGCHAR ,
 422 .Dv GLOB_NOMAGIC ,
 423 and
 424 .Dv GLOB_TILDE ,
 425 and the fields
 426 .Fa gl_matchc
 427 and
 428 .Fa gl_flags
 429 are extensions to the
 430 .Tn POSIX
 431 standard and
 432 should not be used by applications striving for strict
 433 conformance.
 434 .Sh HISTORY
 435 The
 436 .Fn glob
 437 and
 438 .Fn globfree
 439 functions first appeared in
 440 .Bx 4.4 .
 441 .Sh BUGS
 442 Patterns longer than
 443 .Dv MAXPATHLEN
 444 may cause unchecked errors.
 445 .Pp
 446 The
 447 .Fn glob
 448 argument
 449 may fail and set errno for any of the errors specified for the
 450 library routines
 451 .Xr stat 2 ,
 452 .Xr closedir 3 ,
 453 .Xr opendir 3 ,
 454 .Xr readdir 3 ,
 455 .Xr malloc 3 ,
 456 and
 457 .Xr free 3 .