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