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