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