1.\" $NetBSD: glob.3,v 1.45 2022/12/04 11:25:08 uwe 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 May 28, 2019 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_TILDE_CHECK 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. 288If the user with the given user name (or the user id of the current user 289in the case of 290.Dq ~/ ) 291is not found, the original pattern is returned. 292.It Dv GLOB_TILDE_CHECK 293When used with 294.Dv GLOB_TILDE 295and the user name or the user id is not found, then 296.Dv GLOB_NOMATCH 297is returned instead of the original pattern. 298.El 299.Pp 300If, during the search, a directory is encountered that cannot be opened 301or read and 302.Fa errfunc 303is 304.Pf non- Dv NULL , 305.Fn glob 306calls 307.Fa (*errfunc)(path, errno) . 308This may be unintuitive: a pattern like 309.Ql */Makefile 310will try to 311.Xr stat 2 312.Ql foo/Makefile 313even if 314.Ql foo 315is not a directory, resulting in a 316call to 317.Fa errfunc . 318The error routine can suppress this action by testing for 319.Er ENOENT 320and 321.Er ENOTDIR ; 322however, the 323.Dv GLOB_ERR 324flag will still cause an immediate 325return when this happens. 326.Pp 327If 328.Fa errfunc 329returns non-zero, 330.Fn glob 331stops the scan and returns 332.Dv GLOB_ABORTED 333after setting 334.Fa gl_pathc 335and 336.Fa gl_pathv 337to reflect any paths already matched. 338This also happens if an error is encountered and 339.Dv GLOB_ERR 340is set in 341.Fa flags , 342regardless of the return value of 343.Fa errfunc , 344if called. 345If 346.Dv GLOB_ERR 347is not set and either 348.Fa errfunc 349is 350.Dv NULL 351or 352.Fa errfunc 353returns zero, the error is ignored. 354.Pp 355The 356.Fn globfree 357function frees any space associated with 358.Fa pglob 359from a previous call(s) to 360.Fn glob . 361.Pp 362The 363.Fn glob_pattern_p 364returns 365.Dv 1 366if the 367.Fa pattern 368has any special characters that 369.Fn glob 370will interpret and 371.Dv 0 372otherwise. 373If the 374.Fa quote 375argument is non-zero, then backslash quoted characters are ignored. 376.Pp 377The historical 378.Dv GLOB_QUOTE 379flag is no longer supported. 380Per 381.St -p1003.2-92 , 382backslash escaping of special characters is the default behaviour; 383it may be disabled by specifying the 384.Dv GLOB_NOESCAPE 385flag. 386.Sh RETURN VALUES 387On successful completion, 388.Fn glob 389returns zero. 390In addition the fields of 391.Fa pglob 392contain the values described below: 393.Bl -tag -width GLOB_NOCHECK 394.It Fa gl_pathc 395contains the total number of matched pathnames so far. 396This includes other matches from previous invocations of 397.Fn glob 398if 399.Dv GLOB_APPEND 400was specified. 401.It Fa gl_matchc 402contains the number of matched pathnames in the current invocation of 403.Fn glob . 404.It Fa gl_flags 405contains a copy of the 406.Fa flags 407parameter with the bit 408.Dv GLOB_MAGCHAR 409set if 410.Fa pattern 411contained any of the special characters ``*'', ``?'' or ``['', cleared 412if not. 413.It Fa gl_pathv 414contains a pointer to a 415.Dv NULL Ns -terminated 416list of matched pathnames. 417However, if 418.Fa gl_pathc 419is zero, the contents of 420.Fa gl_pathv 421are undefined. 422.El 423.Pp 424If 425.Fn glob 426terminates due to an error, it sets 427.Va errno 428and returns one of the following non-zero constants, which are defined 429in the include file 430.In glob.h : 431.Bl -tag -width GLOB_ABORTEDXXX 432.It Dv GLOB_ABORTED 433The scan was stopped because an error was encountered and either 434.Dv GLOB_ERR 435was set or 436.Fa (*errfunc)() 437returned non-zero. 438.It Dv GLOB_NOMATCH 439The pattern does not match any existing pathname, and 440.Dv GLOB_NOCHECK 441was not set in 442.Dv flags . 443.It Dv GLOB_NOSPACE 444An attempt to allocate memory failed, or if 445.Va errno 446was 0 447.Li GLOB_LIMIT 448was specified in the flags and 449.Li ARG_MAX 450patterns were matched. 451.El 452.Pp 453The historical 454.Dv GLOB_ABEND 455return constant is no longer supported. 456Portable applications should use the 457.Dv GLOB_ABORTED 458constant instead. 459.Pp 460The arguments 461.Fa pglob\->gl_pathc 462and 463.Fa pglob\->gl_pathv 464are still set as specified above. 465.Sh ENVIRONMENT 466.Bl -tag -width HOME -compact 467.It Ev HOME 468If defined, used as the home directory of the current user in 469tilde expansions. 470.El 471.Sh EXAMPLES 472A rough equivalent of 473.Ql "ls -l *.c *.h" 474can be obtained with the 475following code: 476.Bd -literal -offset indent 477glob_t g; 478 479g.gl_offs = 2; 480glob("*.c", GLOB_DOOFFS, NULL, &g); 481glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g); 482g.gl_pathv[0] = "ls"; 483g.gl_pathv[1] = "-l"; 484execvp("ls", g.gl_pathv); 485.Ed 486.Sh SEE ALSO 487.Xr sh 1 , 488.Xr fnmatch 3 , 489.Xr regexp 3 , 490.Xr glob 7 491.Sh STANDARDS 492The 493.Fn glob 494function is expected to be 495.St -p1003.2 496compatible with the exception 497that the flags 498.Dv GLOB_ALTDIRFUNC , 499.Dv GLOB_BRACE , 500.Dv GLOB_LIMIT , 501.Dv GLOB_MAGCHAR , 502.Dv GLOB_NOESCAPE , 503.Dv GLOB_NOMAGIC , 504.Dv GLOB_NO_DOTDIRS , 505.Dv GLOB_PERIOD , 506.Dv GLOB_STAR , 507.Dv GLOB_TILDE , 508and the fields 509.Fa gl_matchc 510and 511.Fa gl_flags 512should not be used by applications striving for strict 513.Tn POSIX 514conformance. 515.Sh HISTORY 516The 517.Fn glob 518and 519.Fn globfree 520functions first appeared in 521.Bx 4.4 . 522The 523.Fn glob_pattern_p 524function is modelled after the one found in glibc. 525.Sh BUGS 526Patterns longer than 527.Dv MAXPATHLEN 528may cause unchecked errors. 529.Pp 530The 531.Fn glob 532function may fail and set 533.Va errno 534for any of the errors specified for the library routines 535.Xr stat 2 , 536.Xr closedir 3 , 537.Xr opendir 3 , 538.Xr readdir 3 , 539.Xr malloc 3 , 540and 541.Xr free 3 . 542