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