1.\" Copyright (c) 1989, 1991 The Regents of the University of California. 2.\" 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 5.7 (Berkeley) 12/2/92 35.\" $Id: glob.3,v 1.3 1993/07/30 08:36:56 mycroft Exp $ 36.\" 37.Dd December 2, 1992 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)(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_NOCHECK 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_NOMAGIC 192Is the same as 193.Dv GLOB_NOCHECK 194but it only appends the 195.Fa pattern 196if it does not contain any of the special characters ``*'', ``?'' or ``[''. 197.Dv GLOB_NOMAGIC 198is provided to simplify implementing the historic 199.Xr csh 1 200globbing behavior and should probably not be used anywhere else. 201.It Dv GLOB_NOSORT 202By default, the pathnames are sorted in ascending 203.Tn ASCII 204order; 205this flag prevents that sorting (speeding up 206.Fn glob ) . 207.It Dv GLOB_QUOTE 208Use the backslash 209.Pq Ql \e 210character for quoting: every occurrence of 211a backslash followed by a character in the pattern is replaced by that 212character, avoiding any special interpretation of the character. 213.It Dv GLOB_ALTDIRFUNC 214The following additional fields in the pglob structure have been 215initialized with alternate functions for glob to use to open, read, 216and close directories and to get stat information on names found 217in those directories. 218.Bd -literal 219 void *(*gl_opendir)(); 220 struct dirent *(*gl_readdir)(); 221 void (*gl_closedir)(); 222 int (*gl_lstat)(); 223 int (*gl_stat)(); 224.Ed 225.Pp 226This non-standard extension is provided to allow programs such 227as restore to provide globbing from directories stored on tape. 228.El 229.Pp 230If, during the search, a directory is encountered that cannot be opened 231or read and 232.Fa errfunc 233is 234.Pf non- Dv NULL , 235.Fn glob 236calls 237.Fa (*errfunc)(path,errno) . 238This may be unintuitive: a pattern like 239.Ql */Makefile 240will try to 241.Xr stat 2 242.Ql foo/Makefile 243even if 244.Ql foo 245is not a directory, resulting in a 246call to 247.Fa errfunc . 248The error routine can suppress this action by testing for 249.Dv ENOENT 250and 251.Dv ENOTDIR ; 252however, the 253.Dv GLOB_ERR 254flag will still cause an immediate 255return when this happens. 256.Pp 257If 258.Fa errfunc 259returns non-zero, 260.Fn glob 261stops the scan and returns 262.Dv GLOB_ABEND 263after setting 264.Fa gl_pathc 265and 266.Fa gl_pathv 267to reflect any paths already matched. 268This also happens if an error is encountered and 269.Dv GLOB_ERR 270is set in 271.Fa flags , 272regardless of the return value of 273.Fa errfunc , 274if called. 275If 276.Dv GLOB_ERR 277is not set and either 278.Fa errfunc 279is 280.Dv NULL 281or 282.Fa errfunc 283returns zero, the error is ignored. 284.Pp 285The 286.Fn globfree 287function frees any space associated with 288.Fa pglob 289from a previous call(s) to 290.Fn glob . 291.Sh RETURN VALUES 292On successful completion, 293.Fn glob 294returns zero. 295In addition the fields of 296.Fa pglob 297contain the values described below: 298.Bl -tag -width GLOB_NOCHECK 299.It Fa gl_pathc 300contains the total number of matched pathnames so far. 301This includes other matches from previous invocations of 302.Fn glob 303if 304.Dv GLOB_APPEND 305was specified. 306.It Fa gl_matchc 307contains the number of matched pathnames in the current invocation of 308.Fn glob . 309.It Fa gl_flags 310contains a copy of the 311.Fa flags 312parameter with the bit 313.Dv GLOB_MAGCHAR 314set if 315.Fa pattern 316contained any of the special characters ``*'', ``?'' or ``['', cleared 317if not. 318.It Fa gl_pathv 319contains a pointer to a 320.Dv NULL Ns -terminated 321list of matched pathnames. 322However, if 323.Fa gl_pathc 324is zero, the contents of 325.Fa gl_pathv 326are undefined. 327.El 328.Pp 329If 330.Fn glob 331terminates due to an error, it sets errno and returns one of the 332following non-zero constants, which are defined in the include 333file 334.Aq Pa glob.h : 335.Bl -tag -width GLOB_NOCHECK 336.It Dv GLOB_NOSPACE 337An attempt to allocate memory failed. 338.It Dv GLOB_ABEND 339The scan was stopped because an error was encountered and either 340.Dv GLOB_ERR 341was set or 342.Fa (*errfunc)() 343returned non-zero. 344.El 345.Pp 346The arguments 347.Fa pglob\->gl_pathc 348and 349.Fa pglob\->gl_pathv 350are still set as specified above. 351.Sh SEE ALSO 352.Xr sh 1 , 353.Xr fnmatch 3 , 354.Xr wordexp 3 , 355.Xr regexp 3 356.Sh STANDARDS 357The 358.Fn glob 359function is expected to be 360.St -p1003.2 361compatible with the exception 362that the flags 363.Dv GLOB_ALTDIRFUNC 364and 365.Dv GLOB_QUOTE 366and the fields 367.Fa gl_matchc 368and 369.Fa gl_flags 370should not be used by applications striving for strict 371.Tn POSIX 372conformance. 373.Sh EXAMPLE 374A rough equivalent of 375.Ql "ls -l *.c *.h" 376can be obtained with the 377following code: 378.Bd -literal -offset indent 379GLOB_t g; 380 381g.gl_offs = 2; 382glob("*.c", GLOB_DOOFFS, NULL, &g); 383glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g); 384g.gl_pathv[0] = "ls"; 385g.gl_pathv[1] = "-l"; 386execvp("ls", g.gl_pathv); 387.Ed 388.Sh HISTORY 389The 390.Fn glob 391and 392.Fn globfree 393functions are 394.Ud . 395.Sh BUGS 396Patterns longer than 397.Dv MAXPATHLEN 398may cause unchecked errors. 399.Pp 400The 401.Fn glob 402argument 403may fail and set errno for any of the errors specified for the 404library routines 405.Xr stat 2 , 406.Xr closedir 3 , 407.Xr opendir 3 , 408.Xr readdir 3 , 409.Xr malloc 3 , 410and 411.Xr free 3 . 412