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.6 (Berkeley) 07/31/91 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.El 187.Pp 188If, during the search, a directory is encountered that cannot be opened 189or read and 190.Fa errfunc 191is 192.Pf non- Dv NULL , 193.Fn glob 194calls 195.Fa (*errfunc)(path,errno) . 196This may be unintuitive: a pattern like 197.Ql */Makefile 198will try to 199.Xr stat 2 200.Ql foo/Makefile 201even if 202.Ql foo 203is not a directory, resulting in a 204call to 205.Fa errfunc . 206The error routine can suppress this action by testing for 207.Dv ENOENT 208and 209.Dv ENOTDIR ; 210however, the 211.Dv GLOB_ERR 212flag will still cause an immediate 213return when this happens. 214.Pp 215If 216.Fa errfunc 217returns non-zero, 218.Fn glob 219stops the scan and returns 220.Dv GLOB_ABEND 221after setting 222.Fa gl_pathc 223and 224.Fa gl_pathv 225to reflect any paths already matched. 226This also happens if an error is encountered and 227.Dv GLOB_ERR 228is set in 229.Fa flags , 230regardless of the return value of 231.Fa errfunc , 232if called. 233If 234.Dv GLOB_ERR 235is not set and either 236.Fa errfunc 237is 238.Dv NULL 239or 240.Fa errfunc 241returns zero, the error is ignored. 242.Pp 243The 244.Fn globfree 245function frees any space associated with 246.Fa pglob 247from a previous call(s) to 248.Fn glob . 249.Sh RETURN VALUES 250On successful completion, 251.Fn glob 252returns zero. 253In addition the fields of 254.Fa pglob 255contain the values described below: 256.Bl -tag -width GLOB_NOCHECK 257.It Fa gl_pathc 258contains the total number of matched pathnames so far. 259This includes other matches from previous invocations of 260.Fn glob 261if 262.Dv GLOB_APPEND 263was specified. 264.It Fa gl_matchc 265contains the number of matched pathnames in the current invocation of 266.Fn glob . 267.It Fa gl_flags 268contains a copy of the 269.Fa flags 270parameter with the bit 271.Dv GLOB_MAGCHAR 272set if 273.Fa pattern 274contained any of the special characters ``*'', ``?'' or ``['', cleared 275if not. 276.It Fa gl_pathv 277contains a pointer to a 278.Dv NULL Ns -terminated 279list of matched pathnames. 280However, if 281.Fa gl_pathc 282is zero, the contents of 283.Fa gl_pathv 284are undefined. 285.El 286.Pp 287If 288.Fn glob 289terminates due to an error, it sets errno and returns one of the 290following non-zero constants, which are defined in the include 291file 292.Aq Pa glob.h : 293.Bl -tag -width GLOB_NOCHECK 294.It Dv GLOB_NOSPACE 295An attempt to allocate memory failed. 296.It Dv GLOB_ABEND 297The scan was stopped because an error was encountered and either 298.Dv GLOB_ERR 299was set or 300.Fa (*errfunc)() 301returned non-zero. 302.El 303.Pp 304The arguments 305.Fa pglob\->gl_pathc 306and 307.Fa pglob\->gl_pathv 308are still set as specified above. 309.Sh SEE ALSO 310.Xr sh 1 , 311.Xr fnmatch 3 , 312.Xr wordexp 3 , 313.Xr regexp 3 314.Sh STANDARDS 315The 316.Fn glob 317function is expected to be 318.St -p1003.2 319compatible with the exception 320that the flag 321.Dv GLOB_QUOTE 322and the fields 323.Fa gl_matchc 324and 325.Fa gl_flags 326should not be used by applications striving for strict 327.Tn POSIX 328conformance. 329.Sh EXAMPLE 330A rough equivalent of 331.Ql "ls -l *.c *.h" 332can be obtained with the 333following code: 334.Bd -literal -offset indent 335GLOB_t g; 336 337g.gl_offs = 2; 338glob("*.c", GLOB_DOOFFS, NULL, &g); 339glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g); 340g.gl_pathv[0] = "ls"; 341g.gl_pathv[1] = "-l"; 342execvp("ls", g.gl_pathv); 343.Ed 344.Sh HISTORY 345The 346.Fn glob 347and 348.Fn globfree 349functions are 350.Ud . 351.Sh BUGS 352Patterns longer than 353.Dv MAXPATHLEN 354may cause unchecked errors. 355.Pp 356The 357.Fn glob 358argument 359may fail and set errno for any of the errors specified for the 360library routines 361.Xr stat 2 , 362.Xr closedir 3 , 363.Xr opendir 3 , 364.Xr readdir 3 , 365.Xr malloc 3 , 366and 367.Xr free 3 . 368