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