1glob(3C)                 Standard C Library Functions                 glob(3C)
2
3
4

NAME

6       glob, globfree - generate path names matching a pattern
7

SYNOPSIS

9       #include <glob.h>
10
11       int glob(const char *restrict pattern, int flags,
12            int(*errfunc)(const char *epath, int eerrno),
13            glob_t *restrict pglob);
14
15
16       void globfree(glob_t *pglob);
17
18

DESCRIPTION

20       The glob() function is a path name generator.
21
22
23       The globfree() function frees any memory allocated by glob() associated
24       with pglob.
25
26   pattern Argument
27       The argument pattern is  a  pointer  to  a  path  name  pattern  to  be
28       expanded. The glob() function matches all accessible path names against
29       this pattern and develops a list of all path names that match. In order
30       to  have  access  to  a path name, glob() requires search permission on
31       every component of a path except the last, and read permission on  each
32       directory of any filename component of pattern that contains any of the
33       following special characters:
34
35         *        ?        [
36
37
38   pglob Argument
39       The structure type  glob_t  is  defined  in  the  header  <glob.h>  and
40       includes at least the following members:
41
42         size_t   gl_pathc;     /* count of paths matched by */
43                                /* pattern */
44         char     **gl_pathv;   /* pointer to list of matched */
45                                /* path names */
46         size_t   gl_offs;      /* slots to reserve at beginning */
47                                /* of gl_pathv */
48
49
50
51       The  glob()  function  stores  the  number  of  matched path names into
52       pglob−>gl_pathc and a pointer to a list of pointers to path names  into
53       pglob−>gl_pathv.  The  path  names  are in sort order as defined by the
54       current setting of the  LC_COLLATE category. The  first  pointer  after
55       the last path name is a NULL pointer. If the pattern does not match any
56       path names, the returned number of matched paths is set to 0,  and  the
57       contents of pglob−>gl_pathv are implementation-dependent.
58
59
60       It is the caller's responsibility to create the structure pointed to by
61       pglob. The glob() function allocates other space as  needed,  including
62       the  memory  pointed  to by gl_pathv. The globfree() function frees any
63       space associated with pglob from a previous call to glob().
64
65   flags Argument
66       The flags argument is used to control the behavior of glob(). The value
67       of  flags  is  a  bitwise inclusive OR of zero or more of the following
68       constants, which are defined in the header <glob.h>:
69
70       GLOB_APPEND      Append path names generated to the ones from a  previ‐
71                        ous call to glob().
72
73
74       GLOB_DOOFFS      Make  use  of  pglob−>gl_offs.  If  this  flag is set,
75                        pglob−>gl_offs is used to specify how many NULL point‐
76                        ers  to  add  to  the beginning of pglob−>gl_pathv. In
77                        other   words,   pglob−>gl_pathv   will    point    to
78                        pglob−>gl_offs     NULL    pointers,    followed    by
79                        pglob−>gl_pathc path name pointers, followed by a NULL
80                        pointer.
81
82
83       GLOB_ERR         Causes glob() to return when it encounters a directory
84                        that it cannot open or read. Ordinarily,  glob()  con‐
85                        tinues to find matches.
86
87
88       GLOB_MARK        Each  path  name that is a directory that matches pat‐
89                        tern has a slash appended.
90
91
92       GLOB_NOCHECK     If pattern does not match any path name,  then  glob()
93                        returns  a  list  consisting  of only pattern, and the
94                        number of matched path names is 1.
95
96
97       GLOB_NOESCAPE    Disable backslash escaping.
98
99
100       GLOB_NOSORT      Ordinarily,  glob()  sorts  the  matching  path  names
101                        according  to  the  current  setting of the LC_COLLATE
102                        category.  When this flag is used the  order  of  path
103                        names returned is unspecified.
104
105
106
107       The  GLOB_APPEND  flag can be used to append a new set of path names to
108       those found in a previous call to glob().  The  following  rules  apply
109       when  two or more calls to glob() are made with the same value of pglob
110       and without intervening calls to globfree():
111
112           1.     The first such call must not set GLOB_APPEND. All subsequent
113                  calls must set it.
114
115           2.     All the calls must set GLOB_DOOFFS, or all must not set it.
116
117           3.     After the second call, pglob−>gl_pathv points to a list con‐
118                  taining the following:
119
120               a.     Zero or more NULL pointers, as specified by  GLOB_DOOFFS
121                      and pglob−>gl_offs.
122
123               b.     Pointers   to   the   path   names   that  were  in  the
124                      pglob−>gl_pathv list before the call, in the same  order
125                      as before.
126
127               c.     Pointers  to  the new path names generated by the second
128                      call, in the specified order.
129
130           4.     The count returned in pglob−>gl_pathc will be the total num‐
131                  ber of path names from the two calls.
132
133           5.     The application can change any of the fields after a call to
134                  glob(). If it does, it must reset them to the original value
135                  before  a  subsequent  call,  using the same pglob value, to
136                  globfree() or glob() with the GLOB_APPEND flag.
137
138   errfunc and epath Arguments
139       If, during the search, a directory is encountered that cannot be opened
140       or read and errfunc is not a NULL pointer, glob() calls (*errfunc) with
141       two arguments:
142
143           1.     The epath argument is a pointer to the path that failed.
144
145           2.     The eerrno argument is the value of errno from the  failure,
146                  as set by the opendir(3C), readdir(3C) or stat(2) functions.
147                  (Other values may be used to report other errors not explic‐
148                  itly documented for those functions.)
149
150
151       The following constants are defined as error return values for glob():
152
153       GLOB_ABORTED    The  scan  was  stopped  because  GLOB_ERR  was  set or
154                       (*errfunc) returned non-zero.
155
156
157       GLOB_NOMATCH    The pattern does not match any existing path name,  and
158                       GLOB_NOCHECK was not set in flags.
159
160
161       GLOG_NOSPACE    An attempt to allocate memory failed.
162
163
164
165       If  (*errfunc)  is called and returns non-zero, or if the GLOB_ERR flag
166       is set in flags, glob() stops the scan and returns  GLOB_ABORTED  after
167       setting  gl_pathc  and  gl_pathv  in pglob to reflect the paths already
168       scanned. If GLOB_ERR is not set and either errfunc is a NULL pointer or
169       (*errfunc) returns 0, the error is ignored.
170

RETURN VALUES

172       The following values are returned by glob():
173
174       0           Successful completion. The argument pglob−>gl_pathc returns
175                   the  number  of  matched  path  names  and   the   argument
176                   pglob−>gl_pathv  contains  a  pointer  to a null-terminated
177                   list  of  matched  and  sorted  path  names.  However,   if
178                   pglob−>gl_pathc  is  0,  the  content of pglob−>gl_pathv is
179                   undefined.
180
181
182       non-zero    An error has occurred. Non-zero constants  are  defined  in
183                   <glob.h>. The arguments pglob−>gl_pathc and pglob−>gl_pathv
184                   are still set as defined above.
185
186
187
188       The globfree() function returns no value.
189

USAGE

191       This function is not provided for the purpose of enabling utilities  to
192       perform  path  name  expansion on their arguments, as this operation is
193       performed by the shell, and utilities are explicitly  not  expected  to
194       redo  this.  Instead,  it  is provided for applications that need to do
195       path name expansion on strings obtained from other sources, such  as  a
196       pattern typed by a user or read from a file.
197
198
199       If  a  utility  needs to see if a path name matches a given pattern, it
200       can use fnmatch(3C).
201
202
203       Note that gl_pathc and gl_pathv have meaning even if glob() fails. This
204       allows  glob() to report partial results in the event of an error. How‐
205       ever, if gl_pathc is 0, gl_pathv is unspecified even if glob() did  not
206       return an error.
207
208
209       The  GLOB_NOCHECK  option  could  be  used when an application wants to
210       expand a path name if wildcards are specified, but wants to  treat  the
211       pattern as just a string otherwise.
212
213
214       The  new path names generated by a subsequent call with GLOB_APPEND are
215       not sorted together with the previous path names. This mirrors the  way
216       that the shell handles path name expansion when multiple expansions are
217       done on a command line.
218
219
220       Applications that need tilde and parameter  expansion  should  use  the
221       wordexp(3C) function.
222

EXAMPLES

224       Example 1 Example of glob_doofs function.
225
226
227       One  use of the GLOB_DOOFFS flag is by applications that build an argu‐
228       ment list for use with the execv(),  execve(),  or  execvp()  functions
229       (see  exec(2)).  Suppose,  for example, that an application wants to do
230       the equivalent of:
231
232
233         ls -l *.c
234
235
236
237       but for some reason:
238
239
240         system("ls -l *.c")
241
242
243
244       is not acceptable. The application could obtain approximately the  same
245       result using the sequence:
246
247
248         globbuf.gl_offs = 2;
249         glob ("*.c", GLOB_DOOFFS, NULL, &globbuf);
250         globbuf.gl_pathv[0] = "ls";
251         globbuf.gl_pathv[1] = "-l";
252         execvp ("ls", &globbuf.gl_pathv[0]);
253
254
255
256       Using the same example:
257
258
259         ls -l *.c *.h
260
261
262
263       could be approximately simulated using GLOB_APPEND as follows:
264
265
266         globbuf.gl_offs = 2;
267         glob ("*.c", GLOB_DOOFFS, NULL, &globbuf);
268         glob ("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf);
269         ...
270
271

ATTRIBUTES

273       See attributes(5) for descriptions of the following attributes:
274
275
276
277
278       ┌─────────────────────────────┬─────────────────────────────┐
279       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
280       ├─────────────────────────────┼─────────────────────────────┤
281       │Interface Stability          │Standard                     │
282       ├─────────────────────────────┼─────────────────────────────┤
283       │MT-Level                     │MT-Safe                      │
284       └─────────────────────────────┴─────────────────────────────┘
285

SEE ALSO

287       execv(2),  stat(2), fnmatch(3C), opendir(3C), readdir(3C), wordexp(3C),
288       attributes(5), standards(5)
289
290
291
292SunOS 5.11                        1 Nov 2003                          glob(3C)
Impressum