Penguin
Recent Changes
Annotated edit history of glob(3) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 GLOB
2 !!!GLOB
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 RETURN VALUE
7 EXAMPLES
8 CONFORMING TO
9 BUGS
10 NOTES
11 SEE ALSO
12 ----
13 !!NAME
14
15
16 glob, globfree - find pathnames matching a pattern, free memory from glob()
17 !!SYNOPSIS
18
19
20 __#include
21 __''pattern''__, int__ ''flags''__,
22 int__ ''errfunc''__(const char *__ ''epath''__, int__ ''eerrno''__),
23 glob_t__ ''*pglob''__);
24 void globfree(glob_t *__''pglob''__);
25 __
26 !!DESCRIPTION
27
28
29 The __glob()__ function searches for all the pathnames
30 matching ''pattern'' according to the rules used by the
31 shell (see glob(7)). No tilde expansion or parameter
32 substitution is done; if you want these, use
33 wordexp(3).
34
35
36 The __globfree()__ function frees the dynamically
37 allocated storage from an earlier call to
38 __glob()__.
39
40
41 The results of a __glob()__ call are stored in the
42 structure pointed to by ''pglob'', which is a
43 __glob_t__ which is declared in ____ and
44 includes the following elements defined by POSIX.2 (more may
45 be present as an extension):
46
47
48 typedef struct
49 {
50 size_t gl_pathc; /* Count of paths matched so far */
51 char **gl_pathv; /* List of matched pathnames. */
52 size_t gl_offs; /* Slots to reserve in `gl_pathv'. */
53 } glob_t;
54 Results are stored in dynamically allocated storage.
55
56
57 The parameter ''flags'' is made up of bitwise OR of zero
58 or more the following symbolic constants, which modify the
59 of behaviour of __glob()__:
60
61
62 __GLOB_ERR__
63
64
65 which means to return upon read error (because a directory
66 does not have read permission, for example),
67
68
69 __GLOB_MARK__
70
71
72 which means to append a slash to each path which corresponds
73 to a directory,
74
75
76 __GLOB_NOSORT__
77
78
79 which means don't sort the returned pathnames (they are by
80 default),
81
82
83 __GLOB_DOOFFS__
84
85
86 which means that ''pglob-'' slots will be
87 reserved at the beginning of the list of strings in
88 ''pglob-'',
89
90
91 __GLOB_NOCHECK__
92
93
94 which means that, if no pattern matches, to return the
95 original pattern,
96
97
98 __GLOB_APPEND__
99
100
101 which means to append to the results of a previous call. Do
102 not set this flag on the first invocation of
103 __glob()__.
104
105
106 __GLOB_NOESCAPE__
107
108
109 which means that meta characters cannot be quoted by
110 backslashes.
111
112
113 The flags may also include some of the following, which are
114 GNU extensions and not defined by POSIX.2:
115
116
117 __GLOB_PERIOD__
118
119
120 which means that a leading period can be matched by meta
121 characters,
122
123
124 __GLOB_ALTDIRFUNC__
125
126
127 which means that alternative functions
128 ''pglob-'', ''pglob-'',
129 ''pglob-'', ''pglob-'', and
130 ''pglob-'' are used for file system access
131 instead of the normal library functions,
132
133
134 __GLOB_BRACE__
135
136
137 which means that csh(1) style brace expresions
138 __{a,b}__ are expanded,
139
140
141 __GLOB_NOMAGIC__
142
143
144 which means that the pattern is returned if it contains no
145 metacharacters,
146
147
148 __GLOB_TILDE__
149
150
151 which means that tilde expansion is carried out,
152 and
153
154
155 __GLOB_ONLYDIR__
156
157
158 which means that only directories are matched.
159
160
161 If ''errfunc'' is not __NULL__, it will be called in
162 case of an error with the arguments ''epath'', a pointer
163 to the path which failed, and ''eerrno'', the value of
164 ''errno'' as returned from one of the calls to
165 __opendir()__, __readdir()__, or __stat()__. If
166 ''errfunc'' returns non-zero, or if __GLOB_ERR__ is
167 set, __glob()__ will terminate after the call to
168 ''errfunc''.
169
170
171 Upon successful return, ''pglob-'' contains
172 the number of matched pathnames and
173 ''pglob-'' a pointer to the list of matched
174 pathnames. The first pointer after the last pathname is
175 __NULL__.
176
177
178 It is possible to call __glob()__ several times. In that
179 case, the __GLOB_APPEND__ flag has to be set in
180 ''flags'' on the second and later
181 invocations.
182
183
184 As a GNU extension, ''pglob-'' is set to the
185 flags specified, __or__ed with __GLOB_MAGCHAR__ if any
186 metacharacters were found.
187 !!RETURN VALUE
188
189
190 On successful completion, __glob()__ returns zero. Other
191 possible returns are:
192
193
194 __GLOB_NOSPACE__
195
196
197 for running out of memory,
198
199
200 __GLOB_ABORTED__
201
202
203 for a read error, and
204
205
206 __GLOB_NOMATCH__
207
208
209 for no found matches.
210 !!EXAMPLES
211
212
213 One example of use is the following code, which simulates
214 typing __ls -l *.c ../*.c__ in the shell.
215
216
217 glob_t globbuf;
218 globbuf.gl_offs = 2;
219 glob(
220 !!CONFORMING TO
221
222
223 POSIX.2
224 !!BUGS
225
226
227 The __glob()__ function may fail due to failure of
228 underlying function calls, such as __malloc()__ or
229 __opendir()__. These will store their error code in
230 ''errno''.
231 !!NOTES
232
233
234 The structure elements ''gl_pathc'' and ''gl_offs''
235 are declared as __size_t__ in glibc 2.1, as they should
236 according to POSIX.2, but are declared as __int__ in
237 libc4, libc5 and glibc 2.0.
238 !!SEE ALSO
239
240
241 ls(1), sh(1), stat(2), exec(3),
242 malloc(3), opendir(3), readdir(3),
243 wordexp(3)
244 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.