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