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