[444] | 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 . |
---|