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