1GLOB(3P)                   POSIX Programmer's Manual                  GLOB(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       glob, globfree - generate pathnames matching a pattern
13

SYNOPSIS

15       #include <glob.h>
16
17       int glob(const char *restrict pattern, int flags,
18              int(*errfunc)(const char *epath, int eerrno),
19              glob_t *restrict pglob);
20       void globfree(glob_t *pglob);
21
22

DESCRIPTION

24       The glob() function is a pathname generator that  shall  implement  the
25       rules    defined    in    the    Shell    and   Utilities   volume   of
26       IEEE Std 1003.1-2001, Section 2.13,  Pattern  Matching  Notation,  with
27       optional  support  for  rule  3  in  the  Shell and Utilities volume of
28       IEEE Std 1003.1-2001, Section 2.13.3, Patterns Used for Filename Expan‐
29       sion.
30
31       The  structure type glob_t is defined in <glob.h> and includes at least
32       the following members:
33
34       Member Type Member Name Description
35       size_t      gl_pathc    Count of paths matched by pattern.
36       char **     gl_pathv    Pointer to a list of matched pathnames.
37       size_t      gl_offs     Slots to reserve at the beginning of gl_pathv.
38
39       The argument pattern is a pointer to a pathname pattern to be expanded.
40       The  glob()  function shall match all accessible pathnames against this
41       pattern and develop a list of all pathnames that  match.  In  order  to
42       have  access  to a pathname, glob() requires search permission on every
43       component of a path except the last, and read permission on each direc‐
44       tory of any filename component of pattern that contains any of the fol‐
45       lowing special characters: '*', '?', and '[' .
46
47       The glob() function shall store the number of  matched  pathnames  into
48       pglob->gl_pathc  and  a pointer to a list of pointers to pathnames into
49       pglob->gl_pathv. The pathnames shall be in sort order as defined by the
50       current  setting  of  the LC_COLLATE category; see the Base Definitions
51       volume of IEEE Std 1003.1-2001, Section 7.3.2,  LC_COLLATE.  The  first
52       pointer after the last pathname shall be a null pointer. If the pattern
53       does not match any pathnames, the returned number of matched  paths  is
54       set  to  0,  and  the  contents  of pglob->gl_pathv are implementation-
55       defined.
56
57       It is the caller's responsibility to create the structure pointed to by
58       pglob.  The  glob()  function  shall  allocate  other  space as needed,
59       including the memory pointed to by gl_pathv.  The  globfree()  function
60       shall  free  any  space  associated  with pglob from a previous call to
61       glob().
62
63       The flags argument is used to control  the  behavior  of  glob().   The
64       value of flags is a bitwise-inclusive OR of zero or more of the follow‐
65       ing constants, which are defined in <glob.h>:
66
67       GLOB_APPEND
68              Append pathnames generated to the ones from a previous  call  to
69              glob().
70
71       GLOB_DOOFFS
72              Make  use of pglob->gl_offs. If this flag is set, pglob->gl_offs
73              is used to specify how many null pointers to add to  the  begin‐
74              ning  of pglob->gl_pathv.  In other words, pglob->gl_pathv shall
75              point   to   pglob->gl_offs   null   pointers,    followed    by
76              pglob->gl_pathc pathname pointers, followed by a null pointer.
77
78       GLOB_ERR
79              Cause  glob()  to  return when it encounters a directory that it
80              cannot open  or  read.  Ordinarily,  glob()  continues  to  find
81              matches.
82
83       GLOB_MARK
84              Each  pathname  that  is  a directory that matches pattern shall
85              have a slash appended.
86
87       GLOB_NOCHECK
88              Supports  rule  3  in  the  Shell  and   Utilities   volume   of
89              IEEE Std 1003.1-2001, Section 2.13.3, Patterns Used for Filename
90              Expansion. If pattern does not match any pathname,  then  glob()
91              shall  return  a list consisting of only pattern, and the number
92              of matched pathnames is 1.
93
94       GLOB_NOESCAPE
95              Disable backslash escaping.
96
97       GLOB_NOSORT
98              Ordinarily, glob() sorts the matching pathnames according to the
99              current setting of the LC_COLLATE category; see the Base Defini‐
100              tions volume of IEEE Std 1003.1-2001, Section 7.3.2, LC_COLLATE.
101              When  this  flag  is  used,  the  order of pathnames returned is
102              unspecified.
103
104
105       The GLOB_APPEND flag can be used to append a new set  of  pathnames  to
106       those  found in a previous call to glob(). The following rules apply to
107       applications when two or more calls to glob() are made  with  the  same
108       value of pglob and without intervening calls to globfree():
109
110        1. The first such call shall not set GLOB_APPEND. All subsequent calls
111           shall set it.
112
113        2. All the calls shall set GLOB_DOOFFS, or all shall not set it.
114
115        3. After the second call, pglob->gl_pathv points to a list  containing
116           the following:
117
118            a. Zero  or  more  null  pointers, as specified by GLOB_DOOFFS and
119               pglob->gl_offs.
120
121            b. Pointers to the pathnames that were in the pglob->gl_pathv list
122               before the call, in the same order as before.
123
124            c. Pointers  to the new pathnames generated by the second call, in
125               the specified order.
126
127        4. The count returned in pglob->gl_pathc shall be the total number  of
128           pathnames from the two calls.
129
130        5. The  application  can  change  any  of  the  fields after a call to
131           glob().  If it does, the application shall reset them to the origi‐
132           nal  value before a subsequent call, using the same pglob value, to
133           globfree() or glob() with the GLOB_APPEND flag.
134
135       If, during the search, a directory is encountered that cannot be opened
136       or  read  and  errfunc is not a null pointer, glob() calls (*errfunc())
137       with two arguments:
138
139        1. The epath argument is a pointer to the path that failed.
140
141        2. The eerrno argument is the value of errno from the failure, as  set
142           by  opendir(),  readdir(),  or stat(). (Other values may be used to
143           report other errors not explicitly documented for those functions.)
144
145       If (*errfunc()) is called and returns non-zero, or if the GLOB_ERR flag
146       is  set  in  flags,  glob() shall stop the scan and return GLOB_ABORTED
147       after setting gl_pathc and gl_pathv  in  pglob  to  reflect  the  paths
148       already  scanned.  If  GLOB_ERR is not set and either errfunc is a null
149       pointer or (*errfunc()) returns 0, the error shall be ignored.
150
151       The glob() function shall not fail because of large files.
152

RETURN VALUE

154       Upon  successful  completion,  glob()  shall  return  0.  The  argument
155       pglob->gl_pathc  shall  return  the number of matched pathnames and the
156       argument pglob->gl_pathv shall contain a pointer to  a  null-terminated
157       list of matched and sorted pathnames. However, if pglob->gl_pathc is 0,
158       the content of pglob->gl_pathv is undefined.
159
160       The globfree() function shall not return a value.
161
162       If glob() terminates due to an error, it shall return one of  the  non-
163       zero  constants  defined in <glob.h>. The arguments pglob->gl_pathc and
164       pglob->gl_pathv are still set as defined above.
165

ERRORS

167       The glob() function shall fail and return the corresponding value if:
168
169       GLOB_ABORTED
170              The scan was stopped because GLOB_ERR was  set  or  (*errfunc())
171              returned non-zero.
172
173       GLOB_NOMATCH
174              The   pattern   does   not  match  any  existing  pathname,  and
175              GLOB_NOCHECK was not set in flags.
176
177       GLOB_NOSPACE
178              An attempt to allocate memory failed.
179
180
181       The following sections are informative.
182

EXAMPLES

184       One use of the GLOB_DOOFFS flag is by applications that build an  argu‐
185       ment  list  for  use with execv(), execve(), or execvp().  Suppose, for
186       example, that an application wants to do the equivalent of:
187
188
189              ls -l *.c
190
191       but for some reason:
192
193
194              system("ls -l *.c")
195
196       is not acceptable. The application could obtain approximately the  same
197       result using the sequence:
198
199
200              globbuf.gl_offs = 2;
201              glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
202              globbuf.gl_pathv[0] = "ls";
203              globbuf.gl_pathv[1] = "-l";
204              execvp("ls", &globbuf.gl_pathv[0]);
205
206       Using the same example:
207
208
209              ls -l *.c *.h
210
211       could be approximately simulated using GLOB_APPEND as follows:
212
213
214              globbuf.gl_offs = 2;
215              glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
216              glob("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf);
217              ...
218

APPLICATION USAGE

220       This  function is not provided for the purpose of enabling utilities to
221       perform pathname expansion on their arguments,  as  this  operation  is
222       performed  by  the  shell, and utilities are explicitly not expected to
223       redo this. Instead, it is provided for applications  that  need  to  do
224       pathname  expansion  on  strings obtained from other sources, such as a
225       pattern typed by a user or read from a file.
226
227       If a utility needs to see if a pathname matches a given pattern, it can
228       use fnmatch().
229
230       Note that gl_pathc and gl_pathv have meaning even if glob() fails. This
231       allows glob() to report partial results in the event of an error.  How‐
232       ever,  if gl_pathc is 0, gl_pathv is unspecified even if glob() did not
233       return an error.
234
235       The GLOB_NOCHECK option could be used  when  an  application  wants  to
236       expand  a  pathname  if wildcards are specified, but wants to treat the
237       pattern as just a string otherwise. The sh utility might use  this  for
238       option-arguments, for example.
239
240       The  new  pathnames generated by a subsequent call with GLOB_APPEND are
241       not sorted together with the previous pathnames. This mirrors  the  way
242       that  the shell handles pathname expansion when multiple expansions are
243       done on a command line.
244
245       Applications that need tilde and parameter expansion should  use  word‐
246       exp().
247

RATIONALE

249       It  was  claimed  that  the  GLOB_DOOFFS flag is unnecessary because it
250       could be simulated using:
251
252
253              new = (char **)malloc((n + pglob->gl_pathc + 1)
254                     * sizeof(char *));
255              (void) memcpy(new+n, pglob->gl_pathv,
256                     pglob->gl_pathc * sizeof(char *));
257              (void) memset(new, 0, n * sizeof(char *));
258              free(pglob->gl_pathv);
259              pglob->gl_pathv = new;
260
261       However, this assumes that the memory pointed to by gl_pathv is a block
262       that was separately created using malloc(). This is not necessarily the
263       case. An application should make no assumptions about  how  the  memory
264       referenced  by  fields  in  pglob  was  allocated.   It might have been
265       obtained from malloc() in a large  chunk  and  then  carved  up  within
266       glob(),  or it might have been created using a different memory alloca‐
267       tor. It is not the intent of the  standard  developers  to  specify  or
268       imply how the memory used by glob() is managed.
269
270       The  GLOB_APPEND flag would be used when an application wants to expand
271       several different patterns into a single list.
272

FUTURE DIRECTIONS

274       None.
275

SEE ALSO

277       exec(), fnmatch(), opendir(), readdir(), stat(),  wordexp(),  the  Base
278       Definitions  volume  of  IEEE Std 1003.1-2001,  <glob.h>, the Shell and
279       Utilities volume of IEEE Std 1003.1-2001
280
282       Portions of this text are reprinted and reproduced in  electronic  form
283       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
284       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
285       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
286       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
287       event of any discrepancy between this version and the original IEEE and
288       The Open Group Standard, the original IEEE and The Open Group  Standard
289       is  the  referee document. The original Standard can be obtained online
290       at http://www.opengroup.org/unix/online.html .
291
292
293
294IEEE/The Open Group                  2003                             GLOB(3P)
Impressum