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