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