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