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" "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 . 224The pattern 225.Ql {} 226is left unexpanded for historical reasons (and 227.Xr csh 1 228does the same thing to 229ease typing 230of 231.Xr find 1 232patterns). 233.It Dv GLOB_MAGCHAR 234Set by the 235.Fn glob 236function if the pattern included globbing characters. 237See the description of the usage of the 238.Fa gl_matchc 239structure member for more details. 240.It Dv GLOB_NOMAGIC 241Is the same as 242.Dv GLOB_NOCHECK 243but it only appends the 244.Fa pattern 245if it does not contain any of the special characters ``*'', ``?'' or ``[''. 246.Dv GLOB_NOMAGIC 247is provided to simplify implementing the historic 248.Xr csh 1 249globbing behavior and should probably not be used anywhere else. 250.It Dv GLOB_QUOTE 251Use the backslash 252.Pq Ql \e 253character for quoting: every occurrence of 254a backslash followed by a character in the pattern is replaced by that 255character, avoiding any special interpretation of the character. 256.It Dv GLOB_TILDE 257Expand patterns that start with 258.Ql ~ 259to user name home directories. 260.El 261.Pp 262If, during the search, a directory is encountered that cannot be opened 263or read and 264.Fa errfunc 265is 266.Pf non- Dv NULL , 267.Fn glob 268calls 269.Fa (*errfunc)(path, errno) . 270This may be unintuitive: a pattern like 271.Ql */Makefile 272will try to 273.Xr stat 2 274.Ql foo/Makefile 275even if 276.Ql foo 277is not a directory, resulting in a 278call to 279.Fa errfunc . 280The error routine can suppress this action by testing for 281.Dv ENOENT 282and 283.Dv ENOTDIR ; 284however, the 285.Dv GLOB_ERR 286flag will still cause an immediate 287return when this happens. 288.Pp 289If 290.Fa errfunc 291returns non-zero, 292.Fn glob 293stops the scan and returns 294.Dv GLOB_ABEND 295after setting 296.Fa gl_pathc 297and 298.Fa gl_pathv 299to reflect any paths already matched. 300This also happens if an error is encountered and 301.Dv GLOB_ERR 302is set in 303.Fa flags , 304regardless of the return value of 305.Fa errfunc , 306if called. 307If 308.Dv GLOB_ERR 309is not set and either 310.Fa errfunc 311is 312.Dv NULL 313or 314.Fa errfunc 315returns zero, the error is ignored. 316.Pp 317The 318.Fn globfree 319function frees any space associated with 320.Fa pglob 321from a previous call(s) to 322.Fn glob . 323.Sh RETURN VALUES 324On successful completion, 325.Fn glob 326returns zero. 327In addition the fields of 328.Fa pglob 329contain the values described below: 330.Bl -tag -width GLOB_NOCHECK 331.It Fa gl_pathc 332contains the total number of matched pathnames so far. 333This includes other matches from previous invocations of 334.Fn glob 335if 336.Dv GLOB_APPEND 337was specified. 338.It Fa gl_matchc 339contains the number of matched pathnames in the current invocation of 340.Fn glob . 341.It Fa gl_flags 342contains a copy of the 343.Fa flags 344parameter with the bit 345.Dv GLOB_MAGCHAR 346set if 347.Fa pattern 348contained any of the special characters ``*'', ``?'' or ``['', cleared 349if not. 350.It Fa gl_pathv 351contains a pointer to a 352.Dv NULL Ns -terminated 353list of matched pathnames. 354However, if 355.Fa gl_pathc 356is zero, the contents of 357.Fa gl_pathv 358are undefined. 359.El 360.Pp 361If 362.Fn glob 363terminates due to an error, it sets errno and returns one of the 364following non-zero constants, which are defined in the include 365file 366.Aq Pa glob.h : 367.Bl -tag -width GLOB_NOCHECK 368.It Dv GLOB_NOSPACE 369An attempt to allocate memory failed. 370.It Dv GLOB_ABEND 371The scan was stopped because an error was encountered and either 372.Dv GLOB_ERR 373was set or 374.Fa (*errfunc)() 375returned non-zero. 376.El 377.Pp 378The arguments 379.Fa pglob\->gl_pathc 380and 381.Fa pglob\->gl_pathv 382are still set as specified above. 383.Sh EXAMPLE 384A rough equivalent of 385.Ql "ls -l *.c *.h" 386can be obtained with the 387following code: 388.Bd -literal -offset indent 389glob_t g; 390 391g.gl_offs = 2; 392glob("*.c", GLOB_DOOFFS, NULL, &g); 393glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g); 394g.gl_pathv[0] = "ls"; 395g.gl_pathv[1] = "-l"; 396execvp("ls", g.gl_pathv); 397.Ed 398.Sh SEE ALSO 399.Xr sh 1 , 400.Xr fnmatch 3 , 401.Xr regexp 3 402.Sh STANDARDS 403The 404.Fn glob 405function is expected to be 406.St -p1003.2 407compatible with the exception 408that the flags 409.Dv GLOB_ALTDIRFUNC, 410.Dv GLOB_BRACE 411.Dv GLOB_MAGCHAR, 412.Dv GLOB_NOMAGIC, 413.Dv GLOB_QUOTE, 414and 415.Dv GLOB_TILDE, 416and the fields 417.Fa gl_matchc 418and 419.Fa gl_flags 420should not be used by applications striving for strict 421.Tn POSIX 422conformance. 423.Sh HISTORY 424The 425.Fn glob 426and 427.Fn globfree 428functions first appeared in 429.Bx 4.4 . 430.Sh BUGS 431Patterns longer than 432.Dv MAXPATHLEN 433may cause unchecked errors. 434.Pp 435The 436.Fn glob 437argument 438may fail and set errno for any of the errors specified for the 439library routines 440.Xr stat 2 , 441.Xr closedir 3 , 442.Xr opendir 3 , 443.Xr readdir 3 , 444.Xr malloc 3 , 445and 446.Xr free 3 . 447