contrib/tcsh/glob.3

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