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.\" 36.Dd April 16, 1994 37.Dt GLOB 3 38.Os 39.Sh NAME 40.Nm glob , 41.Nm globfree 42.Nd generate pathnames matching a pattern 43.Sh SYNOPSIS 44.Fd #include <glob.h> 45.Ft int 46.Fn glob "const char *pattern" "int flags" "const 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.Pa glob.h 58defines the structure type 59.Fa glob_t , 60which contains at least the following fields: 61.Bd -literal 62typedef struct { 63 int gl_pathc; /* count of total paths so far */ 64 int gl_matchc; /* count of paths matching pattern */ 65 int 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.Pa 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 is set to 1, and the number of matched 186pathnames set to 0. 187If 188.Dv GLOB_QUOTE 189is set, its effect is present in the pattern returned. 190.It Dv GLOB_NOSORT 191By default, the pathnames are sorted in ascending 192.Tn ASCII 193order; 194this flag prevents that sorting (speeding up 195.Fn glob ) . 196.El 197.Pp 198The following values may also be included in 199.Fa flags , 200however, they are non-standard extensions to 201.St -p1003.2 . 202.Bl -tag -width GLOB_ALTDIRFUNC 203.It Dv GLOB_ALTDIRFUNC 204The following additional fields in the pglob structure have been 205initialized with alternate functions for glob to use to open, read, 206and close directories and to get stat information on names found 207in those directories. 208.Bd -literal 209void *(*gl_opendir)(const char * name); 210struct dirent *(*gl_readdir)(void *); 211void (*gl_closedir)(void *); 212int (*gl_lstat)(const char *name, struct stat *st); 213int (*gl_stat)(const char *name, struct stat *st); 214.Ed 215.Pp 216This extension is provided to allow programs such as 217.Xr restore 8 218to provide globbing from directories stored on tape. 219.It Dv GLOB_BRACE 220Pre-process the pattern string to expand 221.Ql {pat,pat,...} 222strings like 223.Xr csh 1. The pattern 224.Ql {} 225is left unexpanded for historical reasons 226.Xr (Csh 1 227does the same thing to 228ease typing 229of 230.Xr find 1 231patterns). 232.It Dv GLOB_MAGCHAR 233Set by the 234.Fn glob 235function if the pattern included globbing characters. 236See the description of the usage of the 237.Fa gl_matchc 238structure member for more details. 239.It Dv GLOB_NOMAGIC 240Is the same as 241.Dv GLOB_NOCHECK 242but it only appends the 243.Fa pattern 244if it does not contain any of the special characters ``*'', ``?'' or ``[''. 245.Dv GLOB_NOMAGIC 246is provided to simplify implementing the historic 247.Xr csh 1 248globbing behavior and should probably not be used anywhere else. 249.It Dv GLOB_QUOTE 250Use the backslash 251.Pq Ql \e 252character for quoting: every occurrence of 253a backslash followed by a character in the pattern is replaced by that 254character, avoiding any special interpretation of the character. 255.It Dv GLOB_TILDE 256Expand patterns that start with 257.Ql ~ 258to user name home directories. 259.El 260.Pp 261If, during the search, a directory is encountered that cannot be opened 262or read and 263.Fa errfunc 264is 265.Pf non- Dv NULL , 266.Fn glob 267calls 268.Fa (*errfunc)(path, errno) . 269This may be unintuitive: a pattern like 270.Ql */Makefile 271will try to 272.Xr stat 2 273.Ql foo/Makefile 274even if 275.Ql foo 276is not a directory, resulting in a 277call to 278.Fa errfunc . 279The error routine can suppress this action by testing for 280.Dv ENOENT 281and 282.Dv ENOTDIR ; 283however, the 284.Dv GLOB_ERR 285flag will still cause an immediate 286return when this happens. 287.Pp 288If 289.Fa errfunc 290returns non-zero, 291.Fn glob 292stops the scan and returns 293.Dv GLOB_ABEND 294after setting 295.Fa gl_pathc 296and 297.Fa gl_pathv 298to reflect any paths already matched. 299This also happens if an error is encountered and 300.Dv GLOB_ERR 301is set in 302.Fa flags , 303regardless of the return value of 304.Fa errfunc , 305if called. 306If 307.Dv GLOB_ERR 308is not set and either 309.Fa errfunc 310is 311.Dv NULL 312or 313.Fa errfunc 314returns zero, the error is ignored. 315.Pp 316The 317.Fn globfree 318function frees any space associated with 319.Fa pglob 320from a previous call(s) to 321.Fn glob . 322.Sh RETURN VALUES 323On successful completion, 324.Fn glob 325returns zero. 326In addition the fields of 327.Fa pglob 328contain the values described below: 329.Bl -tag -width GLOB_NOCHECK 330.It Fa gl_pathc 331contains the total number of matched pathnames so far. 332This includes other matches from previous invocations of 333.Fn glob 334if 335.Dv GLOB_APPEND 336was specified. 337.It Fa gl_matchc 338contains the number of matched pathnames in the current invocation of 339.Fn glob . 340.It Fa gl_flags 341contains a copy of the 342.Fa flags 343parameter with the bit 344.Dv GLOB_MAGCHAR 345set if 346.Fa pattern 347contained any of the special characters ``*'', ``?'' or ``['', cleared 348if not. 349.It Fa gl_pathv 350contains a pointer to a 351.Dv NULL Ns -terminated 352list of matched pathnames. 353However, if 354.Fa gl_pathc 355is zero, the contents of 356.Fa gl_pathv 357are undefined. 358.El 359.Pp 360If 361.Fn glob 362terminates due to an error, it sets errno and returns one of the 363following non-zero constants, which are defined in the include 364file 365.Aq Pa glob.h : 366.Bl -tag -width GLOB_NOCHECK 367.It Dv GLOB_NOSPACE 368An attempt to allocate memory failed. 369.It Dv GLOB_ABEND 370The scan was stopped because an error was encountered and either 371.Dv GLOB_ERR 372was set or 373.Fa (*errfunc)() 374returned non-zero. 375.El 376.Pp 377The arguments 378.Fa pglob\->gl_pathc 379and 380.Fa pglob\->gl_pathv 381are still set as specified above. 382.Sh EXAMPLE 383A rough equivalent of 384.Ql "ls -l *.c *.h" 385can be obtained with the 386following code: 387.Bd -literal -offset indent 388glob_t g; 389 390g.gl_offs = 2; 391glob("*.c", GLOB_DOOFFS, NULL, &g); 392glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g); 393g.gl_pathv[0] = "ls"; 394g.gl_pathv[1] = "-l"; 395execvp("ls", g.gl_pathv); 396.Ed 397.Sh SEE ALSO 398.Xr sh 1 , 399.Xr fnmatch 3 , 400.Xr regexp 3 401.Sh STANDARDS 402The 403.Fn glob 404function is expected to be 405.St -p1003.2 406compatible with the exception 407that the flags 408.Dv GLOB_ALTDIRFUNC, 409.Dv GLOB_BRACE 410.Dv GLOB_MAGCHAR, 411.Dv GLOB_NOMAGIC, 412.Dv GLOB_QUOTE, 413and 414.Dv GLOB_TILDE, 415and the fields 416.Fa gl_matchc 417and 418.Fa gl_flags 419should not be used by applications striving for strict 420.Tn POSIX 421conformance. 422.Sh HISTORY 423The 424.Fn glob 425and 426.Fn globfree 427functions first appeared in 4.4BSD. 428.Sh BUGS 429Patterns longer than 430.Dv MAXPATHLEN 431may cause unchecked errors. 432.Pp 433The 434.Fn glob 435argument 436may fail and set errno for any of the errors specified for the 437library routines 438.Xr stat 2 , 439.Xr closedir 3 , 440.Xr opendir 3 , 441.Xr readdir 3 , 442.Xr malloc 3 , 443and 444.Xr free 3 . 445