1.\" Copyright (c) 1989, 1991, 1993 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.\" from: @(#)glob.3 8.1 (Berkeley) 6/9/93 35.\" $Id: glob.3,v 1.8 1994/01/06 13:24:09 deraadt Exp $ 36.\" 37.Dd June 9, 1993 38.Dt GLOB 3 39.Os 40.Sh NAME 41.Nm glob , 42.Nm globfree 43.Nd generate pathnames matching a pattern 44.Sh SYNOPSIS 45.Fd #include <glob.h> 46.Ft int 47.Fn glob "const char *pattern" "int flags" "const int (*errfunc)(const char *, int)" "glob_t *pglob" 48.Ft void 49.Fn globfree "glob_t *pglob" 50.Sh DESCRIPTION 51The 52.Fn glob 53function 54is a pathname generator that implements the rules for file name pattern 55matching used by the shell. 56.Pp 57The include file 58.Pa glob.h 59defines the structure type 60.Fa glob_t , 61which contains at least the following fields: 62.Bd -literal 63typedef struct { 64 int gl_pathc; /* count of total paths so far */ 65 int gl_matchc; /* count of paths matching pattern */ 66 int gl_offs; /* reserved at beginning of gl_pathv */ 67 int gl_flags; /* returned flags */ 68 char **gl_pathv; /* list of paths matching pattern */ 69} glob_t; 70.Ed 71.Pp 72The argument 73.Fa pattern 74is a pointer to a pathname pattern to be expanded. 75The 76.Fn glob 77argument 78matches all accessible pathnames against the pattern and creates 79a list of the pathnames that match. 80In order to have access to a pathname, 81.Fn glob 82requires search permission on every component of a path except the last 83and read permission on each directory of any filename component of 84.Fa pattern 85that contains any of the special characters 86.Ql * , 87.Ql ? 88or 89.Ql [ . 90.Pp 91The 92.Fn glob 93argument 94stores the number of matched pathnames into the 95.Fa gl_pathc 96field, and a pointer to a list of pointers to pathnames into the 97.Fa gl_pathv 98field. 99The first pointer after the last pathname is 100.Dv NULL . 101If the pattern does not match any pathnames, the returned number of 102matched paths is set to zero. 103.Pp 104It is the caller's responsibility to create the structure pointed to by 105.Fa pglob . 106The 107.Fn glob 108function allocates other space as needed, including the memory pointed 109to by 110.Fa gl_pathv . 111.Pp 112The argument 113.Fa flags 114is used to modify the behavior of 115.Fn glob . 116The value of 117.Fa flags 118is the bitwise inclusive 119.Tn OR 120of any of the following 121values defined in 122.Pa glob.h : 123.Bl -tag -width GLOB_ALTDIRFUNC 124.It Dv GLOB_APPEND 125Append pathnames generated to the ones from a previous call (or calls) 126to 127.Fn glob . 128The value of 129.Fa gl_pathc 130will be the total matches found by this call and the previous call(s). 131The pathnames are appended to, not merged with the pathnames returned by 132the previous call(s). 133Between calls, the caller must not change the setting of the 134.Dv GLOB_DOOFFS 135flag, nor change the value of 136.Fa gl_offs 137when 138.Dv GLOB_DOOFFS 139is set, nor (obviously) call 140.Fn globfree 141for 142.Fa pglob . 143.It Dv GLOB_DOOFFS 144Make use of the 145.Fa gl_offs 146field. 147If this flag is set, 148.Fa gl_offs 149is used to specify how many 150.Dv NULL 151pointers to prepend to the beginning 152of the 153.Fa gl_pathv 154field. 155In other words, 156.Fa gl_pathv 157will point to 158.Fa gl_offs 159.Dv NULL 160pointers, 161followed by 162.Fa gl_pathc 163pathname pointers, followed by a 164.Dv NULL 165pointer. 166.It Dv GLOB_ERR 167Causes 168.Fn glob 169to return when it encounters a directory that it cannot open or read. 170Ordinarily, 171.Fn glob 172continues to find matches. 173.It Dv GLOB_MARK 174Each pathname that is a directory that matches 175.Fa pattern 176has a slash 177appended. 178.It Dv GLOB_NOCHECK 179If 180.Fa pattern 181does not match any pathname, then 182.Fn glob 183returns a list 184consisting of only 185.Fa pattern , 186with the number of total pathnames is set to 1, and the number of matched 187pathnames set to 0. 188If 189.Dv GLOB_QUOTE 190is set, its effect is present in the pattern returned. 191.It Dv GLOB_NOSORT 192By default, the pathnames are sorted in ascending 193.Tn ASCII 194order; 195this flag prevents that sorting (speeding up 196.Fn glob ) . 197.El 198.Pp 199The following values may also be included in 200.Fa flags , 201however, they are non-standard extensions to 202.St -p1003.2 . 203.Bl -tag -width GLOB_ALTDIRFUNC 204.It Dv GLOB_ALTDIRFUNC 205The following additional fields in the pglob structure have been 206initialized with alternate functions for glob to use to open, read, 207and close directories and to get stat information on names found 208in those directories. 209.Bd -literal 210 void *(*gl_opendir)(const char * name); 211 struct dirent *(*gl_readdir)(void *); 212 void (*gl_closedir)(void *); 213 int (*gl_lstat)(const char *name, struct stat *st); 214 int (*gl_stat)(const char *name, struct stat *st); 215.Ed 216.Pp 217This extension is provided to allow programs such as 218.Xr restore 8 219to provide globbing from directories stored on tape. 220.It Dv GLOB_BRACE 221Pre-process the pattern string to expand 222.Ql {pat,pat,...} 223strings like 224.Xr csh 1. The pattern 225.Ql {} 226is left unexpanded for historical reasons 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 364.Va errno 365and returns one of the following non-zero constants, which are defined 366in the include file 367.Aq Pa glob.h : 368.Bl -tag -width GLOB_NOCHECK 369.It Dv GLOB_NOSPACE 370An attempt to allocate memory failed. 371.It Dv GLOB_ABEND 372The scan was stopped because an error was encountered and either 373.Dv GLOB_ERR 374was set or 375.Fa (*errfunc)() 376returned non-zero. 377.El 378.Pp 379The arguments 380.Fa pglob\->gl_pathc 381and 382.Fa pglob\->gl_pathv 383are still set as specified above. 384.Sh SEE ALSO 385.Xr sh 1 , 386.Xr fnmatch 3 , 387.Xr wordexp 3 , 388.Xr regexp 3 389.Sh STANDARDS 390The 391.Fn glob 392function is expected to be 393.St -p1003.2 394compatible with the exception 395that the flags 396.Dv GLOB_ALTDIRFUNC, 397.Dv GLOB_BRACE 398.Dv GLOB_MAGCHAR, 399.Dv GLOB_NOMAGIC, 400.Dv GLOB_QUOTE, 401and 402.Dv GLOB_TILDE, 403and the fields 404.Fa gl_matchc 405and 406.Fa gl_flags 407should not be used by applications striving for strict 408.Tn POSIX 409conformance. 410.Sh EXAMPLE 411A rough equivalent of 412.Ql "ls -l *.c *.h" 413can be obtained with the 414following code: 415.Bd -literal -offset indent 416glob_t g; 417 418g.gl_offs = 2; 419glob("*.c", GLOB_DOOFFS, NULL, &g); 420glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g); 421g.gl_pathv[0] = "ls"; 422g.gl_pathv[1] = "-l"; 423execvp("ls", g.gl_pathv); 424.Ed 425.Sh HISTORY 426The 427.Fn glob 428and 429.Fn globfree 430functions first appeared in 431.Bx 4.4 . 432.Sh BUGS 433Patterns longer than 434.Dv MAXPATHLEN 435may cause unchecked errors. 436.Pp 437The 438.Fn glob 439function may fail and set 440.Va errno 441for any of the errors specified for the library routines 442.Xr stat 2 , 443.Xr closedir 3 , 444.Xr opendir 3 , 445.Xr readdir 3 , 446.Xr malloc 3 , 447and 448.Xr free 3 . 449