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