1.\" $NetBSD: glob.3,v 1.36 2010/03/22 19:30:54 joerg Exp $ 2.\" 3.\" Copyright (c) 1989, 1991, 1993, 1994 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" Guido van Rossum. 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)glob.3 8.3 (Berkeley) 4/16/94 33.\" 34.Dd April 8, 2009 35.Dt GLOB 3 36.Os 37.Sh NAME 38.Nm glob , 39.Nm globfree , 40.Nm glob_pattern_p 41.Nd generate pathnames matching a pattern 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In glob.h 46.Ft int 47.Fn glob "const char * restrict pattern" "int flags" "const int (*errfunc)(const char *, int)" "glob_t * restrict pglob" 48.Ft void 49.Fn globfree "glob_t *pglob" 50.Ft int 51.Fn glob_pattern_p "const char *pattern" "int quote" 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 size_t gl_pathc; /* count of total paths so far */ 67 size_t gl_matchc; /* count of paths matching pattern */ 68 size_t 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 set to 1, and the number of matched 189pathnames set to 0. 190.It Dv GLOB_NOSORT 191By default, the pathnames are sorted in ascending 192.Tn ASCII 193order; 194this flag prevents that sorting (speeding up 195.Fn glob ) . 196.El 197.Pp 198The following values may also be included in 199.Fa flags , 200however, they are non-standard extensions to 201.St -p1003.2 . 202.Bl -tag -width GLOB_ALTDIRFUNC 203.It Dv GLOB_ALTDIRFUNC 204The following additional fields in the pglob structure have been 205initialized with alternate functions for glob to use to open, read, 206and close directories and to get stat information on names found 207in those directories. 208.Bd -literal 209 void *(*gl_opendir)(const char * name); 210 struct dirent *(*gl_readdir)(void *); 211 void (*gl_closedir)(void *); 212 int (*gl_lstat)(const char *name, struct stat *st); 213 int (*gl_stat)(const char *name, struct stat *st); 214.Ed 215.Pp 216This extension is provided to allow programs such as 217.Xr restore 8 218to provide globbing from directories stored on tape. 219.It Dv GLOB_BRACE 220Pre-process the pattern string to expand 221.Ql {pat,pat,...} 222strings like 223.Xr csh 1 . 224The pattern 225.Ql {} 226is left unexpanded for historical reasons 227.Po 228.Xr csh 1 229does the same thing to ease typing of 230.Xr find 1 231patterns 232.Pc . 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_NOESCAPE 251Disable the use of the backslash 252.Pq Ql \e 253character for quoting. 254.It Dv GLOB_TILDE 255Expand patterns that start with 256.Ql ~ 257to user name home directories. 258.It Dv GLOB_LIMIT 259Limit the amount of memory used by matches to 260.Li ARG_MAX . 261This option should be set for programs that can be coerced to a denial of 262service attack via patterns that expand to a very large number of matches, 263such as a long string of 264.Li */../*/.. 265.It Dv GLOB_PERIOD 266Allow metacharacters to match a leading period in a filename. 267.It Dv GLOB_NO_DOTDIRS 268Hide 269.Sq Li \&. 270and 271.Sq Li \&.. 272from metacharacter matches, regardless of whether 273.Dv GLOB_PERIOD 274is set and whether the pattern component begins with a literal period. 275.El 276.Pp 277If, during the search, a directory is encountered that cannot be opened 278or read and 279.Fa errfunc 280is 281.Pf non- Dv NULL , 282.Fn glob 283calls 284.Fa (*errfunc)(path, errno) . 285This may be unintuitive: a pattern like 286.Ql */Makefile 287will try to 288.Xr stat 2 289.Ql foo/Makefile 290even if 291.Ql foo 292is not a directory, resulting in a 293call to 294.Fa errfunc . 295The error routine can suppress this action by testing for 296.Dv ENOENT 297and 298.Dv ENOTDIR ; 299however, the 300.Dv GLOB_ERR 301flag will still cause an immediate 302return when this happens. 303.Pp 304If 305.Fa errfunc 306returns non-zero, 307.Fn glob 308stops the scan and returns 309.Dv GLOB_ABORTED 310after setting 311.Fa gl_pathc 312and 313.Fa gl_pathv 314to reflect any paths already matched. 315This also happens if an error is encountered and 316.Dv GLOB_ERR 317is set in 318.Fa flags , 319regardless of the return value of 320.Fa errfunc , 321if called. 322If 323.Dv GLOB_ERR 324is not set and either 325.Fa errfunc 326is 327.Dv NULL 328or 329.Fa errfunc 330returns zero, the error is ignored. 331.Pp 332The 333.Fn globfree 334function frees any space associated with 335.Fa pglob 336from a previous call(s) to 337.Fn glob . 338.Pp 339The 340.Fn glob_pattern_p 341returns 342.Dv 1 343if the 344.Fa pattern 345has any special characters that 346.Fn glob 347will interpret and 348.Dv 0 349otherwise. 350If the 351.Fa quote 352argument is non-zero, then backslash quoted characters are ignored. 353.Pp 354The historical 355.Dv GLOB_QUOTE 356flag is no longer supported. 357Per 358.St -p1003.2-92 , 359backslash escaping of special characters is the default behaviour; 360it may be disabled by specifying the 361.Dv GLOB_NOESCAPE 362flag. 363.Sh RETURN VALUES 364On successful completion, 365.Fn glob 366returns zero. 367In addition the fields of 368.Fa pglob 369contain the values described below: 370.Bl -tag -width GLOB_NOCHECK 371.It Fa gl_pathc 372contains the total number of matched pathnames so far. 373This includes other matches from previous invocations of 374.Fn glob 375if 376.Dv GLOB_APPEND 377was specified. 378.It Fa gl_matchc 379contains the number of matched pathnames in the current invocation of 380.Fn glob . 381.It Fa gl_flags 382contains a copy of the 383.Fa flags 384parameter with the bit 385.Dv GLOB_MAGCHAR 386set if 387.Fa pattern 388contained any of the special characters ``*'', ``?'' or ``['', cleared 389if not. 390.It Fa gl_pathv 391contains a pointer to a 392.Dv NULL Ns -terminated 393list of matched pathnames. 394However, if 395.Fa gl_pathc 396is zero, the contents of 397.Fa gl_pathv 398are undefined. 399.El 400.Pp 401If 402.Fn glob 403terminates due to an error, it sets 404.Va errno 405and returns one of the following non-zero constants, which are defined 406in the include file 407.In glob.h : 408.Bl -tag -width GLOB_ABORTEDXXX 409.It Dv GLOB_ABORTED 410The scan was stopped because an error was encountered and either 411.Dv GLOB_ERR 412was set or 413.Fa (*errfunc)() 414returned non-zero. 415.It Dv GLOB_NOMATCH 416The pattern does not match any existing pathname, and 417.Dv GLOB_NOCHECK 418was not set in 419.Dv flags . 420.It Dv GLOB_NOSPACE 421An attempt to allocate memory failed, or if 422.Va errno 423was 0 424.Li GLOB_LIMIT 425was specified in the flags and 426.Li ARG_MAX 427patterns were matched. 428.El 429.Pp 430The historical 431.Dv GLOB_ABEND 432return constant is no longer supported. 433Portable applications should use the 434.Dv GLOB_ABORTED 435constant instead. 436.Pp 437The arguments 438.Fa pglob\-\*[Gt]gl_pathc 439and 440.Fa pglob\-\*[Gt]gl_pathv 441are still set as specified above. 442.Sh ENVIRONMENT 443.Bl -tag -width HOME -compact 444.It Ev HOME 445If defined, used as the home directory of the current user in 446tilde expansions. 447.El 448.Sh EXAMPLES 449A rough equivalent of 450.Ql "ls -l *.c *.h" 451can be obtained with the 452following code: 453.Bd -literal -offset indent 454glob_t g; 455 456g.gl_offs = 2; 457glob("*.c", GLOB_DOOFFS, NULL, \*[Am]g); 458glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, \*[Am]g); 459g.gl_pathv[0] = "ls"; 460g.gl_pathv[1] = "-l"; 461execvp("ls", g.gl_pathv); 462.Ed 463.Sh SEE ALSO 464.Xr sh 1 , 465.Xr fnmatch 3 , 466.Xr regexp 3 467.Sh STANDARDS 468The 469.Fn glob 470function is expected to be 471.St -p1003.2 472compatible with the exception 473that the flags 474.Dv GLOB_ALTDIRFUNC , 475.Dv GLOB_BRACE , 476.Dv GLOB_MAGCHAR , 477.Dv GLOB_NOMAGIC , 478.Dv GLOB_TILDE , 479and 480.Dv GLOB_LIMIT 481and the fields 482.Fa gl_matchc 483and 484.Fa gl_flags 485should not be used by applications striving for strict 486.Tn POSIX 487conformance. 488.Sh HISTORY 489The 490.Fn glob 491and 492.Fn globfree 493functions first appeared in 494.Bx 4.4 . 495The 496.Fn glob_pattern_p 497function is modelled after the one found in glibc. 498.Sh BUGS 499Patterns longer than 500.Dv MAXPATHLEN 501may cause unchecked errors. 502.Pp 503The 504.Fn glob 505function may fail and set 506.Va errno 507for any of the errors specified for the library routines 508.Xr stat 2 , 509.Xr closedir 3 , 510.Xr opendir 3 , 511.Xr readdir 3 , 512.Xr malloc 3 , 513and 514.Xr free 3 . 515