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