1.\" $NetBSD: glob.3,v 1.42 2012/12/27 21:17:47 christos 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 December 27, 2012 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" "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 one level of backslash escapes removed, 189the number of total pathnames set to 1, and the number of matched 190pathnames set to 0. 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 210 void *(*gl_opendir)(const char * name); 211 struct dirent *(*gl_readdir)(void *); 212 void (*gl_closedir)(void *); 213 int (*gl_lstat)(const char *name, struct stat *st); 214 int (*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 228.Po 229.Xr csh 1 230does the same thing to ease typing of 231.Xr find 1 232patterns 233.Pc . 234.It Dv GLOB_LIMIT 235Limit the amount of memory used to store matched strings to 236.Li 64K , 237the number of 238.Xr stat 2 239calls to 128, and the number of 240.Xr readdir 3 241calls to 16K. 242This option should be set for programs that can be coerced to a denial of 243service attack via patterns that expand to a very large number of matches, 244such as a long string of 245.Li */../*/.. 246.It Dv GLOB_MAGCHAR 247Set by the 248.Fn glob 249function if the pattern included globbing characters. 250See the description of the usage of the 251.Fa gl_matchc 252structure member for more details. 253.It Dv GLOB_NOESCAPE 254Disable the use of the backslash 255.Pq Ql \e 256character for quoting. 257.It Dv GLOB_NOMAGIC 258Is the same as 259.Dv GLOB_NOCHECK 260but it only appends the 261.Fa pattern 262if it does not contain any of the special characters ``*'', ``?'' or ``[''. 263.Dv GLOB_NOMAGIC 264is provided to simplify implementing the historic 265.Xr csh 1 266globbing behavior and should probably not be used anywhere else. 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.It Dv GLOB_PERIOD 276Allow metacharacters to match a leading period in a filename. 277.It Dv GLOB_STAR 278Indicates that two adjacent 279.Li * 280characters will do a recursive match in all subdirs, without following 281symbolic links and three adjacent 282.Li * 283characters will also follow symbolic links. 284.It Dv GLOB_TILDE 285Expand patterns that start with 286.Ql ~ 287to user name home directories. 288.El 289.Pp 290If, during the search, a directory is encountered that cannot be opened 291or read and 292.Fa errfunc 293is 294.Pf non- Dv NULL , 295.Fn glob 296calls 297.Fa (*errfunc)(path, errno) . 298This may be unintuitive: a pattern like 299.Ql */Makefile 300will try to 301.Xr stat 2 302.Ql foo/Makefile 303even if 304.Ql foo 305is not a directory, resulting in a 306call to 307.Fa errfunc . 308The error routine can suppress this action by testing for 309.Dv ENOENT 310and 311.Dv ENOTDIR ; 312however, the 313.Dv GLOB_ERR 314flag will still cause an immediate 315return when this happens. 316.Pp 317If 318.Fa errfunc 319returns non-zero, 320.Fn glob 321stops the scan and returns 322.Dv GLOB_ABORTED 323after setting 324.Fa gl_pathc 325and 326.Fa gl_pathv 327to reflect any paths already matched. 328This also happens if an error is encountered and 329.Dv GLOB_ERR 330is set in 331.Fa flags , 332regardless of the return value of 333.Fa errfunc , 334if called. 335If 336.Dv GLOB_ERR 337is not set and either 338.Fa errfunc 339is 340.Dv NULL 341or 342.Fa errfunc 343returns zero, the error is ignored. 344.Pp 345The 346.Fn globfree 347function frees any space associated with 348.Fa pglob 349from a previous call(s) to 350.Fn glob . 351.Pp 352The 353.Fn glob_pattern_p 354returns 355.Dv 1 356if the 357.Fa pattern 358has any special characters that 359.Fn glob 360will interpret and 361.Dv 0 362otherwise. 363If the 364.Fa quote 365argument is non-zero, then backslash quoted characters are ignored. 366.Pp 367The historical 368.Dv GLOB_QUOTE 369flag is no longer supported. 370Per 371.St -p1003.2-92 , 372backslash escaping of special characters is the default behaviour; 373it may be disabled by specifying the 374.Dv GLOB_NOESCAPE 375flag. 376.Sh RETURN VALUES 377On successful completion, 378.Fn glob 379returns zero. 380In addition the fields of 381.Fa pglob 382contain the values described below: 383.Bl -tag -width GLOB_NOCHECK 384.It Fa gl_pathc 385contains the total number of matched pathnames so far. 386This includes other matches from previous invocations of 387.Fn glob 388if 389.Dv GLOB_APPEND 390was specified. 391.It Fa gl_matchc 392contains the number of matched pathnames in the current invocation of 393.Fn glob . 394.It Fa gl_flags 395contains a copy of the 396.Fa flags 397parameter with the bit 398.Dv GLOB_MAGCHAR 399set if 400.Fa pattern 401contained any of the special characters ``*'', ``?'' or ``['', cleared 402if not. 403.It Fa gl_pathv 404contains a pointer to a 405.Dv NULL Ns -terminated 406list of matched pathnames. 407However, if 408.Fa gl_pathc 409is zero, the contents of 410.Fa gl_pathv 411are undefined. 412.El 413.Pp 414If 415.Fn glob 416terminates due to an error, it sets 417.Va errno 418and returns one of the following non-zero constants, which are defined 419in the include file 420.In glob.h : 421.Bl -tag -width GLOB_ABORTEDXXX 422.It Dv GLOB_ABORTED 423The scan was stopped because an error was encountered and either 424.Dv GLOB_ERR 425was set or 426.Fa (*errfunc)() 427returned non-zero. 428.It Dv GLOB_NOMATCH 429The pattern does not match any existing pathname, and 430.Dv GLOB_NOCHECK 431was not set in 432.Dv flags . 433.It Dv GLOB_NOSPACE 434An attempt to allocate memory failed, or if 435.Va errno 436was 0 437.Li GLOB_LIMIT 438was specified in the flags and 439.Li ARG_MAX 440patterns were matched. 441.El 442.Pp 443The historical 444.Dv GLOB_ABEND 445return constant is no longer supported. 446Portable applications should use the 447.Dv GLOB_ABORTED 448constant instead. 449.Pp 450The arguments 451.Fa pglob\-\*[Gt]gl_pathc 452and 453.Fa pglob\-\*[Gt]gl_pathv 454are still set as specified above. 455.Sh ENVIRONMENT 456.Bl -tag -width HOME -compact 457.It Ev HOME 458If defined, used as the home directory of the current user in 459tilde expansions. 460.El 461.Sh EXAMPLES 462A rough equivalent of 463.Ql "ls -l *.c *.h" 464can be obtained with the 465following code: 466.Bd -literal -offset indent 467glob_t g; 468 469g.gl_offs = 2; 470glob("*.c", GLOB_DOOFFS, NULL, \*[Am]g); 471glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, \*[Am]g); 472g.gl_pathv[0] = "ls"; 473g.gl_pathv[1] = "-l"; 474execvp("ls", g.gl_pathv); 475.Ed 476.Sh SEE ALSO 477.Xr sh 1 , 478.Xr fnmatch 3 , 479.Xr regexp 3 , 480.Xr glob 7 481.Sh STANDARDS 482The 483.Fn glob 484function is expected to be 485.St -p1003.2 486compatible with the exception 487that the flags 488.Dv GLOB_ALTDIRFUNC , 489.Dv GLOB_BRACE , 490.Dv GLOB_LIMIT , 491.Dv GLOB_MAGCHAR , 492.Dv GLOB_NOESCAPE , 493.Dv GLOB_NOMAGIC , 494.Dv GLOB_NO_DOTDIRS , 495.Dv GLOB_PERIOD , 496.Dv GLOB_STAR , 497.Dv GLOB_TILDE , 498and the fields 499.Fa gl_matchc 500and 501.Fa gl_flags 502should not be used by applications striving for strict 503.Tn POSIX 504conformance. 505.Sh HISTORY 506The 507.Fn glob 508and 509.Fn globfree 510functions first appeared in 511.Bx 4.4 . 512The 513.Fn glob_pattern_p 514function is modelled after the one found in glibc. 515.Sh BUGS 516Patterns longer than 517.Dv MAXPATHLEN 518may cause unchecked errors. 519.Pp 520The 521.Fn glob 522function may fail and set 523.Va errno 524for any of the errors specified for the library routines 525.Xr stat 2 , 526.Xr closedir 3 , 527.Xr opendir 3 , 528.Xr readdir 3 , 529.Xr malloc 3 , 530and 531.Xr free 3 . 532