Commit | Line | Data |
---|---|---|
b4ee7c09 KB |
1 | .\" Copyright (c) 1989 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 | .\" | |
91cff1e1 | 7 | .\" %sccs.include.redist.man% |
b4ee7c09 | 8 | .\" |
f6ec3c7f | 9 | .\" @(#)glob.3 5.3 (Berkeley) %G% |
b4ee7c09 KB |
10 | .\" |
11 | .TH GLOB 3 "" | |
12 | .UC 7 | |
13 | .SH NAME | |
14 | glob, globfree \- generate pathnames matching a pattern | |
15 | .SH SYNOPSIS | |
16 | .nf | |
17 | #include <glob.h> | |
18 | ||
19 | glob(const char *pattern, int flags, | |
20 | const int (*errfunc)(char *, int), glob_t *pglob); | |
21 | ||
22 | void globfree(glob_t *pglob); | |
23 | .fi | |
24 | .SH DESCRIPTION | |
25 | .I Glob | |
26 | is a pathname generator that implements the rules for file name pattern | |
27 | matching used by the shell. | |
28 | .PP | |
29 | The include file | |
30 | .I glob.h | |
31 | defines the structure type | |
32 | .IR glob_t , | |
33 | which contains at least the following fields: | |
34 | .sp | |
35 | .RS | |
36 | .nf | |
37 | .ta .5i +\w'char **gl_pathv;\0\0\0'u | |
38 | typedef struct { | |
f6ec3c7f KB |
39 | int gl_pathc; /* count of total paths so far */ |
40 | int gl_matchc; /* count of paths matching pattern */ | |
b4ee7c09 | 41 | int gl_offs; /* reserved at beginning of gl_pathv */ |
f6ec3c7f | 42 | int gl_flags; /* returned flags */ |
b4ee7c09 KB |
43 | char **gl_pathv; /* list of paths matching pattern */ |
44 | } glob_t; | |
45 | .fi | |
46 | .RE | |
47 | .PP | |
48 | The argument | |
49 | .I pattern | |
50 | is a pointer to a pathname pattern to be expanded. | |
51 | .I Glob | |
52 | matches all accessible pathnames against the pattern and creates | |
53 | a list of the pathnames that match. | |
54 | In order to have access to a pathname, | |
55 | .I glob | |
56 | requires search permission on every component of a path except the last | |
57 | and read permission on each directory of any filename component of | |
58 | .I pattern | |
59 | that contains any of the special characters ``*'', ``?'' or ``[''. | |
60 | .PP | |
61 | .I Glob | |
62 | stores the number of matched pathnames into the | |
63 | .I gl_pathc | |
64 | field, and a pointer to a list of pointers to pathnames into the | |
65 | .I gl_pathv | |
66 | field. | |
67 | The first pointer after the last pathname is NULL. | |
68 | If the pattern does not match any pathnames, the returned number of | |
69 | matched paths is set to zero. | |
70 | .PP | |
71 | It is the caller's responsibility to create the structure pointed to by | |
72 | .IR pglob . | |
73 | The | |
74 | .I glob | |
75 | function allocates other space as needed, including the memory pointed | |
76 | to by | |
77 | .IR gl_pathv . | |
78 | .PP | |
79 | The argument | |
80 | .I flags | |
81 | is used to modify the behavior of | |
82 | .IR glob . | |
83 | The value of | |
84 | .I flags | |
85 | is the bitwise inclusive OR of any of the following | |
86 | values defined in | |
87 | .IR glob.h : | |
88 | .TP | |
89 | GLOB_APPEND | |
90 | Append pathnames generated to the ones from a previous call (or calls) | |
91 | to | |
92 | .IR glob . | |
93 | The value of | |
94 | .I gl_pathc | |
95 | will be the total matches found by this call and the previous call(s). | |
96 | The pathnames are appended to, not merged with the pathnames returned by | |
97 | the previous call(s). | |
98 | Between calls, the caller must not change the setting of the | |
99 | GLOB_DOOFFS flag, nor change the value of | |
100 | .I gl_offs | |
101 | when | |
102 | GLOB_DOOFFS is set, nor (obviously) call | |
103 | .I globfree | |
104 | for | |
105 | .I pglob. | |
106 | .TP | |
107 | GLOB_DOOFFS | |
108 | Make use of the | |
109 | .I gl_offs | |
110 | field. | |
111 | If this flag is set, | |
112 | .I gl_offs | |
113 | is used to specify how many NULL pointers to prepend to the beginning | |
114 | of the | |
115 | .I gl_pathv | |
116 | field. | |
117 | In other words, | |
118 | .I gl_pathv | |
119 | will point to | |
120 | .I gl_offs | |
121 | NULL pointers, | |
122 | followed by | |
123 | .I gl_pathc | |
124 | pathname pointers, followed by a NULL pointer. | |
125 | .TP | |
126 | GLOB_ERR | |
127 | Causes | |
128 | .I glob | |
129 | to return when it encounters a directory that it cannot open or read. | |
130 | Ordinarily, | |
131 | .I glob | |
132 | continues to find matches. | |
133 | .TP | |
134 | GLOB_MARK | |
135 | Each pathname that is a directory that matches | |
136 | .I pattern | |
137 | has a slash | |
138 | appended. | |
139 | .TP | |
140 | GLOB_NOSORT | |
141 | By default, the pathnames are sorted in ascending ASCII order; | |
142 | this flag prevents that sorting (speeding up | |
143 | .IR glob ). | |
144 | .TP | |
145 | GLOB_NOCHECK | |
146 | If | |
147 | .I pattern | |
148 | does not match any pathname, then | |
149 | .I glob | |
150 | returns a list | |
151 | consisting of only | |
152 | .IR pattern , | |
f6ec3c7f KB |
153 | with the number of total pathnames is set to 1, and the number of matched |
154 | pathnames set to 0. | |
b4ee7c09 KB |
155 | If |
156 | .I GLOB_QUOTE | |
157 | is set, its effect is present in the pattern returned. | |
158 | .TP | |
159 | GLOB_QUOTE | |
160 | Use the backslash (``\e'') character for quoting: every occurrence of | |
161 | a backslash followed by a character in the pattern is replaced by that | |
162 | character, avoiding any special interpretation of the character. | |
163 | .PP | |
164 | If, during the search, a directory is encountered that cannot be opened | |
165 | or read and | |
166 | .I errfunc | |
167 | is non-NULL, | |
168 | .I glob | |
169 | calls (*\fIerrfunc\fP)(\fIpath\fP, \fIerrno\fP). | |
170 | This may be unintuitive: a pattern like ``*/Makefile'' will try to | |
171 | .IR stat (2) | |
172 | ``foo/Makefile'' even if ``foo'' is not a directory, resulting in a | |
173 | call to | |
174 | .IR errfunc . | |
175 | The error routine can suppress this action by testing for ENOENT and | |
176 | ENOTDIR; however, the GLOB_ERR flag will still cause an immediate | |
177 | return when this happens. | |
178 | .PP | |
179 | If | |
180 | .I errfunc | |
181 | returns non-zero, | |
182 | .I glob | |
183 | stops the scan and returns | |
184 | .I GLOB_ABEND | |
185 | after setting | |
186 | .I gl_pathc | |
187 | and | |
188 | .I gl_pathv | |
189 | to reflect any paths already matched. | |
190 | This also happens if an error is encountered and | |
191 | .I GLOB_ERR | |
192 | is set in | |
193 | .IR flags , | |
194 | regardless of the return value of | |
195 | .IR errfunc , | |
196 | if called. | |
197 | If | |
198 | .I GLOB_ERR | |
199 | is not set and either | |
200 | .I errfunc | |
201 | is NULL or | |
202 | .I errfunc | |
203 | returns zero, the error is ignored. | |
204 | .PP | |
205 | The | |
206 | .I globfree | |
207 | function frees any space associated with | |
208 | .I pglob | |
209 | from a previous call(s) to | |
210 | .IR glob . | |
211 | .SH RETURNS | |
212 | On successful completion, | |
213 | .I glob | |
214 | returns zero. | |
f6ec3c7f KB |
215 | In addition the fields of |
216 | .I pglob | |
217 | contain the values described below: | |
218 | .TP | |
b4ee7c09 | 219 | .I gl_pathc |
f6ec3c7f KB |
220 | contains the total number of matched pathnames so far. |
221 | This includes other matches from previous invocations of | |
222 | .I glob | |
223 | if | |
224 | .I GLOB_APPEND | |
225 | was specified. | |
226 | .TP | |
227 | .I gl_matchc | |
228 | contains the number of matched pathnames in the current invocation of | |
229 | .I glob. | |
230 | .TP | |
231 | .I gl_flags | |
232 | contains a copy of the | |
233 | .I flags | |
234 | parameter with the bit GLOB_MAGCHAR set if | |
235 | .I pattern | |
236 | contained any of the special characters ``*'', ``?'' or ``['', cleared | |
237 | if not. | |
238 | .TP | |
b4ee7c09 KB |
239 | .I gl_pathv |
240 | contains a pointer to a NULL-terminated list of matched pathnames. | |
241 | However, if | |
f6ec3c7f | 242 | .I gl_pathc |
b4ee7c09 | 243 | is zero, the contents of |
f6ec3c7f KB |
244 | .I gl_pathv |
245 | are undefined. | |
b4ee7c09 KB |
246 | .PP |
247 | If | |
248 | .I glob | |
249 | terminates due to an error, it sets errno and returns one of the | |
250 | following non-zero constants, which are defined in the include | |
251 | file <glob.h>: | |
252 | .TP | |
253 | GLOB_NOSPACE | |
254 | An attempt to allocate memory failed. | |
255 | .TP | |
256 | GLOB_ABEND | |
257 | The scan was stopped because an error was encountered and either | |
258 | GLOB_ERR was set or (*\fIerrfunc\fR)() returned non-zero. | |
259 | .PP | |
260 | The arguments | |
261 | .I pglob->gl_pathc | |
262 | and | |
263 | .I pglob->gl_pathv | |
264 | are still set as specified above. | |
265 | .SH STANDARDS | |
266 | The | |
267 | .I glob | |
268 | function is expected to be POSIX 1003.2 compatible with the exception | |
f6ec3c7f KB |
269 | that the flag |
270 | .I GLOB_QUOTE | |
271 | and the fields | |
272 | .I gl_matchc | |
273 | and | |
274 | .I gl_flags | |
275 | should not be used by applications striving for strict POSIX conformance. | |
b4ee7c09 KB |
276 | .SH EXAMPLE |
277 | A rough equivalent of ``ls -l *.c *.h'' can be obtained with the | |
278 | following code: | |
279 | .sp | |
280 | .nf | |
281 | .RS | |
282 | glob_t g; | |
283 | ||
284 | g.gl_offs = 2; | |
285 | glob("*.c", GLOB_DOOFFS, NULL, &g); | |
286 | glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g); | |
287 | g.gl_pathv[0] = "ls"; | |
288 | g.gl_pathv[1] = "-l"; | |
289 | execvp("ls", g.gl_pathv); | |
290 | .RE | |
291 | .fi | |
292 | .SH SEE ALSO | |
293 | sh(1), fnmatch(3), wordexp(3), regexp(3) | |
294 | .SH BUGS | |
295 | Patterns longer than MAXPATHLEN may cause unchecked errors. | |
296 | .PP | |
297 | .I Glob | |
298 | may fail and set errno for any of the errors specified for the | |
299 | library routines | |
300 | .I stat (2), | |
301 | .I closedir (3), | |
302 | .I opendir (3), | |
303 | .I readdir (3), | |
304 | .I malloc (3), | |
305 | and | |
306 | .I free (3). | |
307 |