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