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