1.\" Copyright (c) 1989, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" Guido van Rossum. 6.\" %sccs.include.redist.man% 7.\" 8.\" @(#)glob.3 5.7 (Berkeley) 12/02/92 9.\" 10.Dd 11.Dt GLOB 3 12.Os 13.Sh NAME 14.Nm glob , 15.Nm globfree 16.Nd generate pathnames matching a pattern 17.Sh SYNOPSIS 18.Fd #include <glob.h> 19.Ft int 20.Fn glob "const char *pattern" "int flags" "const int (*errfunc)(char *, int)" "glob_t *pglob" 21.Ft void 22.Fn globfree "glob_t *pglob" 23.Sh DESCRIPTION 24The 25.Fn glob 26function 27is a pathname generator that implements the rules for file name pattern 28matching used by the shell. 29.Pp 30The include file 31.Pa glob.h 32defines the structure type 33.Fa glob_t , 34which contains at least the following fields: 35.Bd -literal 36typedef struct { 37 int gl_pathc; /* count of total paths so far */ 38 int gl_matchc; /* count of paths matching pattern */ 39 int gl_offs; /* reserved at beginning of gl_pathv */ 40 int gl_flags; /* returned flags */ 41 char **gl_pathv; /* list of paths matching pattern */ 42} glob_t; 43.Ed 44.Pp 45The argument 46.Fa pattern 47is a pointer to a pathname pattern to be expanded. 48The 49.Fn glob 50argument 51matches all accessible pathnames against the pattern and creates 52a list of the pathnames that match. 53In order to have access to a pathname, 54.Fn glob 55requires search permission on every component of a path except the last 56and read permission on each directory of any filename component of 57.Fa pattern 58that contains any of the special characters 59.Ql * , 60.Ql ? 61or 62.Ql [ . 63.Pp 64The 65.Fn glob 66argument 67stores the number of matched pathnames into the 68.Fa gl_pathc 69field, and a pointer to a list of pointers to pathnames into the 70.Fa gl_pathv 71field. 72The first pointer after the last pathname is 73.Dv NULL . 74If the pattern does not match any pathnames, the returned number of 75matched paths is set to zero. 76.Pp 77It is the caller's responsibility to create the structure pointed to by 78.Fa pglob . 79The 80.Fn glob 81function allocates other space as needed, including the memory pointed 82to by 83.Fa gl_pathv . 84.Pp 85The argument 86.Fa flags 87is used to modify the behavior of 88.Fn glob . 89The value of 90.Fa flags 91is the bitwise inclusive 92.Tn OR 93of any of the following 94values defined in 95.Pa glob.h : 96.Bl -tag -width GLOB_NOCHECK 97.It Dv GLOB_APPEND 98Append pathnames generated to the ones from a previous call (or calls) 99to 100.Fn glob . 101The value of 102.Fa gl_pathc 103will be the total matches found by this call and the previous call(s). 104The pathnames are appended to, not merged with the pathnames returned by 105the previous call(s). 106Between calls, the caller must not change the setting of the 107.Dv GLOB_DOOFFS 108flag, nor change the value of 109.Fa gl_offs 110when 111.Dv GLOB_DOOFFS 112is set, nor (obviously) call 113.Fn globfree 114for 115.Fa pglob . 116.It Dv GLOB_DOOFFS 117Make use of the 118.Fa gl_offs 119field. 120If this flag is set, 121.Fa gl_offs 122is used to specify how many 123.Dv NULL 124pointers to prepend to the beginning 125of the 126.Fa gl_pathv 127field. 128In other words, 129.Fa gl_pathv 130will point to 131.Fa gl_offs 132.Dv NULL 133pointers, 134followed by 135.Fa gl_pathc 136pathname pointers, followed by a 137.Dv NULL 138pointer. 139.It Dv GLOB_ERR 140Causes 141.Fn glob 142to return when it encounters a directory that it cannot open or read. 143Ordinarily, 144.Fn glob 145continues to find matches. 146.It Dv GLOB_MARK 147Each pathname that is a directory that matches 148.Fa pattern 149has a slash 150appended. 151.It Dv GLOB_NOCHECK 152If 153.Fa pattern 154does not match any pathname, then 155.Fn glob 156returns a list 157consisting of only 158.Fa pattern , 159with the number of total pathnames is set to 1, and the number of matched 160pathnames set to 0. 161If 162.Dv GLOB_QUOTE 163is set, its effect is present in the pattern returned. 164.It Dv GLOB_NOMAGIC 165Is the same as 166.Dv GLOB_NOCHECK 167but it only appends the 168.Fa pattern 169if it does not contain any of the special characters ``*'', ``?'' or ``[''. 170.Dv GLOB_NOMAGIC 171is provided to simplify implementing the historic 172.Xr csh 1 173globbing behavior and should probably not be used anywhere else. 174.It Dv GLOB_NOSORT 175By default, the pathnames are sorted in ascending 176.Tn ASCII 177order; 178this flag prevents that sorting (speeding up 179.Fn glob ) . 180.It Dv GLOB_QUOTE 181Use the backslash 182.Pq Ql \e 183character for quoting: every occurrence of 184a backslash followed by a character in the pattern is replaced by that 185character, avoiding any special interpretation of the character. 186.It Dv GLOB_ALTDIRFUNC 187The following additional fields in the pglob structure have been 188initialized with alternate functions for glob to use to open, read, 189and close directories and to get stat information on names found 190in those directories. 191.Bd -literal 192 void *(*gl_opendir)(); 193 struct dirent *(*gl_readdir)(); 194 void (*gl_closedir)(); 195 int (*gl_lstat)(); 196 int (*gl_stat)(); 197.Ed 198.Pp 199This non-standard extension is provided to allow programs such 200as restore to provide globbing from directories stored on tape. 201.El 202.Pp 203If, during the search, a directory is encountered that cannot be opened 204or read and 205.Fa errfunc 206is 207.Pf non- Dv NULL , 208.Fn glob 209calls 210.Fa (*errfunc)(path,errno) . 211This may be unintuitive: a pattern like 212.Ql */Makefile 213will try to 214.Xr stat 2 215.Ql foo/Makefile 216even if 217.Ql foo 218is not a directory, resulting in a 219call to 220.Fa errfunc . 221The error routine can suppress this action by testing for 222.Dv ENOENT 223and 224.Dv ENOTDIR ; 225however, the 226.Dv GLOB_ERR 227flag will still cause an immediate 228return when this happens. 229.Pp 230If 231.Fa errfunc 232returns non-zero, 233.Fn glob 234stops the scan and returns 235.Dv GLOB_ABEND 236after setting 237.Fa gl_pathc 238and 239.Fa gl_pathv 240to reflect any paths already matched. 241This also happens if an error is encountered and 242.Dv GLOB_ERR 243is set in 244.Fa flags , 245regardless of the return value of 246.Fa errfunc , 247if called. 248If 249.Dv GLOB_ERR 250is not set and either 251.Fa errfunc 252is 253.Dv NULL 254or 255.Fa errfunc 256returns zero, the error is ignored. 257.Pp 258The 259.Fn globfree 260function frees any space associated with 261.Fa pglob 262from a previous call(s) to 263.Fn glob . 264.Sh RETURN VALUES 265On successful completion, 266.Fn glob 267returns zero. 268In addition the fields of 269.Fa pglob 270contain the values described below: 271.Bl -tag -width GLOB_NOCHECK 272.It Fa gl_pathc 273contains the total number of matched pathnames so far. 274This includes other matches from previous invocations of 275.Fn glob 276if 277.Dv GLOB_APPEND 278was specified. 279.It Fa gl_matchc 280contains the number of matched pathnames in the current invocation of 281.Fn glob . 282.It Fa gl_flags 283contains a copy of the 284.Fa flags 285parameter with the bit 286.Dv GLOB_MAGCHAR 287set if 288.Fa pattern 289contained any of the special characters ``*'', ``?'' or ``['', cleared 290if not. 291.It Fa gl_pathv 292contains a pointer to a 293.Dv NULL Ns -terminated 294list of matched pathnames. 295However, if 296.Fa gl_pathc 297is zero, the contents of 298.Fa gl_pathv 299are undefined. 300.El 301.Pp 302If 303.Fn glob 304terminates due to an error, it sets errno and returns one of the 305following non-zero constants, which are defined in the include 306file 307.Aq Pa glob.h : 308.Bl -tag -width GLOB_NOCHECK 309.It Dv GLOB_NOSPACE 310An attempt to allocate memory failed. 311.It Dv GLOB_ABEND 312The scan was stopped because an error was encountered and either 313.Dv GLOB_ERR 314was set or 315.Fa (*errfunc)() 316returned non-zero. 317.El 318.Pp 319The arguments 320.Fa pglob\->gl_pathc 321and 322.Fa pglob\->gl_pathv 323are still set as specified above. 324.Sh SEE ALSO 325.Xr sh 1 , 326.Xr fnmatch 3 , 327.Xr wordexp 3 , 328.Xr regexp 3 329.Sh STANDARDS 330The 331.Fn glob 332function is expected to be 333.St -p1003.2 334compatible with the exception 335that the flags 336.Dv GLOB_ALTDIRFUNC 337and 338.Dv GLOB_QUOTE 339and the fields 340.Fa gl_matchc 341and 342.Fa gl_flags 343should not be used by applications striving for strict 344.Tn POSIX 345conformance. 346.Sh EXAMPLE 347A rough equivalent of 348.Ql "ls -l *.c *.h" 349can be obtained with the 350following code: 351.Bd -literal -offset indent 352GLOB_t g; 353 354g.gl_offs = 2; 355glob("*.c", GLOB_DOOFFS, NULL, &g); 356glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g); 357g.gl_pathv[0] = "ls"; 358g.gl_pathv[1] = "-l"; 359execvp("ls", g.gl_pathv); 360.Ed 361.Sh HISTORY 362The 363.Fn glob 364and 365.Fn globfree 366functions are 367.Ud . 368.Sh BUGS 369Patterns longer than 370.Dv MAXPATHLEN 371may cause unchecked errors. 372.Pp 373The 374.Fn glob 375argument 376may fail and set errno for any of the errors specified for the 377library routines 378.Xr stat 2 , 379.Xr closedir 3 , 380.Xr opendir 3 , 381.Xr readdir 3 , 382.Xr malloc 3 , 383and 384.Xr free 3 . 385