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.5 2007/06/30 19:03:52 swildner Exp $ 37.\" 38.Dd December 6, 2005 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 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.In 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.In 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 set to 1, and the number of matched 190pathnames set to 0. 191The effect of backslash escaping is present in the pattern returned. 192.It Dv GLOB_NOESCAPE 193By default, a backslash 194.Pq Ql \e 195character is used to escape the following character in the pattern, 196avoiding any special interpretation of the character. 197If 198.Dv GLOB_NOESCAPE 199is set, backslash escaping is disabled. 200.It Dv GLOB_NOSORT 201By default, the pathnames are sorted in ascending 202.Tn ASCII 203order; 204this flag prevents that sorting (speeding up 205.Fn glob ) . 206.El 207.Pp 208The following values may also be included in 209.Fa flags , 210however, they are non-standard extensions to 211.St -p1003.2 . 212.Bl -tag -width GLOB_ALTDIRFUNC 213.It Dv GLOB_ALTDIRFUNC 214The following additional fields in the pglob structure have been 215initialized with alternate functions for glob to use to open, read, 216and close directories and to get stat information on names found 217in those directories. 218.Bd -literal 219void *(*gl_opendir)(const char * name); 220struct dirent *(*gl_readdir)(void *); 221void (*gl_closedir)(void *); 222int (*gl_lstat)(const char *name, struct stat *st); 223int (*gl_stat)(const char *name, struct stat *st); 224.Ed 225.Pp 226This extension is provided to allow programs such as 227.Xr restore 8 228to provide globbing from directories stored on tape. 229.It Dv GLOB_BRACE 230Pre-process the pattern string to expand 231.Ql {pat,pat,...} 232strings like 233.Xr csh 1 . 234The pattern 235.Ql {} 236is left unexpanded for historical reasons (and 237.Xr csh 1 238does the same thing to 239ease typing 240of 241.Xr find 1 242patterns). 243.It Dv GLOB_MAGCHAR 244Set by the 245.Fn glob 246function if the pattern included globbing characters. 247See the description of the usage of the 248.Fa gl_matchc 249structure member for more details. 250.It Dv GLOB_NOMAGIC 251Is the same as 252.Dv GLOB_NOCHECK 253but it only appends the 254.Fa pattern 255if it does not contain any of the special characters ``*'', ``?'' or ``[''. 256.Dv GLOB_NOMAGIC 257is provided to simplify implementing the historic 258.Xr csh 1 259globbing behavior and should probably not be used anywhere else. 260.It Dv GLOB_TILDE 261Expand patterns that start with 262.Ql ~ 263to user name home directories. 264.It Dv GLOB_LIMIT 265Limit the total number of returned pathnames to the value provided in 266.Fa gl_matchc 267(default 268.Dv ARG_MAX ) . 269This option should be set for programs 270that can be coerced into a denial of service attack 271via patterns that expand to a very large number of matches, 272such as a long string of 273.Ql */../*/.. . 274.It Dv GLOB_PERIOD 275Allow matching of pathnames which start with a period. 276.El 277.Pp 278If, during the search, a directory is encountered that cannot be opened 279or read and 280.Fa errfunc 281is 282.Pf non- Dv NULL , 283.Fn glob 284calls 285.Fa \*(lp*errfunc\*(rp Ns ( Fa path , errno ) . 286This may be unintuitive: a pattern like 287.Ql */Makefile 288will try to 289.Xr stat 2 290.Ql foo/Makefile 291even if 292.Ql foo 293is not a directory, resulting in a 294call to 295.Fa errfunc . 296The error routine can suppress this action by testing for 297.Er ENOENT 298and 299.Er ENOTDIR ; 300however, the 301.Dv GLOB_ERR 302flag will still cause an immediate 303return when this happens. 304.Pp 305If 306.Fa errfunc 307returns non-zero, 308.Fn glob 309stops the scan and returns 310.Dv GLOB_ABORTED 311after setting 312.Fa gl_pathc 313and 314.Fa gl_pathv 315to reflect any paths already matched. 316This also happens if an error is encountered and 317.Dv GLOB_ERR 318is set in 319.Fa flags , 320regardless of the return value of 321.Fa errfunc , 322if called. 323If 324.Dv GLOB_ERR 325is not set and either 326.Fa errfunc 327is 328.Dv NULL 329or 330.Fa errfunc 331returns zero, the error is ignored. 332.Pp 333The 334.Fn globfree 335function frees any space associated with 336.Fa pglob 337from a previous call(s) to 338.Fn glob . 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 360argument 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 382following non-zero constants, which are defined in the include file 383.In glob.h : 384.Bl -tag -width GLOB_NOCHECK 385.It Dv GLOB_NOSPACE 386An attempt to allocate memory failed, or if 387.Fa errno 388was 0 389.Dv GLOB_LIMIT 390was specified in the flags and 391.Fa pglob\->gl_matchc 392or more patterns were matched. 393.It Dv GLOB_ABORTED 394The scan was stopped because an error was encountered and either 395.Dv GLOB_ERR 396was set or 397.Fa \*(lp*errfunc\*(rp\*(lp\*(rp 398returned non-zero. 399.It Dv GLOB_NOMATCH 400The pattern did not match a pathname and 401.Dv GLOB_NOCHECK 402was not set. 403.El 404.Pp 405The arguments 406.Fa pglob\->gl_pathc 407and 408.Fa pglob\->gl_pathv 409are still set as specified above. 410.Sh EXAMPLES 411A rough equivalent of 412.Ql "ls -l *.c *.h" 413can be obtained with the 414following code: 415.Bd -literal -offset indent 416glob_t g; 417 418g.gl_offs = 2; 419glob("*.c", GLOB_DOOFFS, NULL, &g); 420glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g); 421g.gl_pathv[0] = "ls"; 422g.gl_pathv[1] = "-l"; 423execvp("ls", g.gl_pathv); 424.Ed 425.Sh SEE ALSO 426.Xr sh 1 , 427.Xr fnmatch 3 , 428.Xr regexp 3 429.Sh STANDARDS 430The 431.Fn glob 432function is expected to be 433.St -p1003.2 434compatible with the exception 435that the flags 436.Dv GLOB_ALTDIRFUNC , 437.Dv GLOB_BRACE , 438.Dv GLOB_LIMIT , 439.Dv GLOB_MAGCHAR , 440.Dv GLOB_NOMAGIC , 441and 442.Dv GLOB_TILDE , 443and the fields 444.Fa gl_matchc 445and 446.Fa gl_flags 447should not be used by applications striving for strict 448.Tn POSIX 449conformance. 450.Sh HISTORY 451The 452.Fn glob 453and 454.Fn globfree 455functions first appeared in 456.Bx 4.4 . 457.Sh BUGS 458Patterns longer than 459.Dv MAXPATHLEN 460may cause unchecked errors. 461.Pp 462The 463.Fn glob 464argument may fail and set 465.Va errno 466for any of the errors specified for the library routines 467.Xr stat 2 , 468.Xr closedir 3 , 469.Xr opendir 3 , 470.Xr readdir 3 , 471.Xr malloc 3 , 472and 473.Xr free 3 . 474