man3/glob.3

   1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\"
   3 .\" %%%LICENSE_START(verbatim)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Modified Wed Jul 28 11:12:17 1993 by Rik Faith (faith@cs.unc.edu)
  26 .\" Modified Mon May 13 23:08:50 1996 by Martin Schulze (joey@linux.de)
  27 .\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
  28 .\" Modified 990912 by aeb
  29 .\" 2007-10-10 mtk
  30 .\"     Added description of GLOB_TILDE_NOMATCH
  31 .\"     Expanded the description of various flags
  32 .\"     Various wording fixes.
  33 .\"
  34 .TH GLOB 3  2007-10-10 "GNU" "Linux Programmer's Manual"
  35 .SH NAME
  36 glob, globfree \- find pathnames matching a pattern, free memory from glob()
  37 .SH SYNOPSIS
  38 .nf
  39 .B #include <glob.h>
  40 .sp
  41 .BI "int glob(const char *" pattern ", int " flags ,
  42 .br
  43 .BI "         int (*" errfunc ") (const char *" epath ", int " eerrno ),
  44 .br
  45 .BI "         glob_t *" pglob );
  46 .br
  47 .BI "void globfree(glob_t *" pglob );
  48 .fi
  49 .SH DESCRIPTION
  50 The
  51 .BR glob ()
  52 function searches for all the pathnames matching
  53 .I pattern
  54 according to the rules used by the shell (see
  55 .BR glob (7)).
  56 No tilde expansion or parameter substitution is done; if you want
  57 these, use
  58 .BR wordexp (3).
  59 .PP
  60 The
  61 .BR globfree ()
  62 function frees the dynamically allocated storage from an earlier call
  63 to
  64 .BR glob ().
  65 .PP
  66 The results of a
  67 .BR glob ()
  68 call are stored in the structure pointed to by
  69 .IR pglob .
  70 This structure is of type
  71 .I glob_t
  72 (declared in
  73 .IR <glob.h> )
  74 and includes the following elements defined by POSIX.2 (more may be
  75 present as an extension):
  76 .PP
  77 .br
  78 .in +4n
  79 .nf
  80 typedef struct {
  81     size_t   gl_pathc;    /* Count of paths matched so far  */
  82     char   **gl_pathv;    /* List of matched pathnames.  */
  83     size_t   gl_offs;     /* Slots to reserve in \fIgl_pathv\fP.  */
  84 } glob_t;
  85 .fi
  86 .in
  87 .PP
  88 Results are stored in dynamically allocated storage.
  89 .PP
  90 The argument
  91 .I flags
  92 is made up of the bitwise OR of zero or more the following symbolic
  93 constants, which modify the behavior of
  94 .BR glob ():
  95 .TP
  96 .B GLOB_ERR
  97 Return upon a read error (because a directory does not
  98 have read permission, for example).
  99 By default,
 100 .BR glob ()
 101 attempts carry on despite errors,
 102 reading all of the directories that it can.
 103 .TP
 104 .B GLOB_MARK
 105 Append a slash to each path which corresponds to a directory.
 106 .TP
 107 .B GLOB_NOSORT
 108 Don't sort the returned pathnames.
 109 The only reason to do this is to save processing time.
 110 By default, the returned pathnames are sorted.
 111 .TP
 112 .B GLOB_DOOFFS
 113 Reserve
 114 .I pglob\->gl_offs
 115 slots at the beginning of the list of strings in
 116 .IR pglob\->pathv .
 117 The reserved slots contain NULL pointers.
 118 .TP
 119 .B GLOB_NOCHECK
 120 If no pattern matches, return the original pattern.
 121 By default,
 122 .BR glob ()
 123 returns
 124 .B GLOB_NOMATCH
 125 if there are no matches.
 126 .TP
 127 .B GLOB_APPEND
 128 Append the results of this call to the vector of results
 129 returned by a previous call to
 130 .BR glob ().
 131 Do not set this flag on the first invocation of
 132 .BR glob ().
 133 .TP
 134 .B GLOB_NOESCAPE
 135 Don't allow backslash (\(aq\\\(aq) to be used as an escape
 136 character.
 137 Normally, a backslash can be used to quote the following character,
 138 providing a mechanism to turn off the special meaning
 139 metacharacters.
 140 .PP
 141 .I flags
 142 may also include any of the following, which are GNU
 143 extensions and not defined by POSIX.2:
 144 .TP
 145 .B GLOB_PERIOD
 146 Allow a leading period to be matched by metacharacters.
 147 By default, metacharacters can't match a leading period.
 148 .TP
 149 .B GLOB_ALTDIRFUNC
 150 Use alternative functions
 151 .IR pglob\->gl_closedir ,
 152 .IR pglob\->gl_readdir ,
 153 .IR pglob\->gl_opendir ,
 154 .IR pglob\->gl_lstat ", and"
 155 .I pglob\->gl_stat
 156 for file system access instead of the normal library
 157 functions.
 158 .TP
 159 .B GLOB_BRACE
 160 Expand
 161 .BR csh (1)
 162 style brace expressions of the form \fB{a,b}\fR.
 163 Brace expressions can be nested.
 164 Thus, for example, specifying the pattern
 165 "{foo/{,cat,dog},bar}" would return the same results as four separate
 166 .BR glob ()
 167 calls using the strings:
 168 "foo/",
 169 "foo/cat",
 170 "foo/dog",
 171 and
 172 "bar".
 173 .TP
 174 .B GLOB_NOMAGIC
 175 If the pattern contains no metacharacters
 176 then it should be returned as the sole matching word,
 177 even if there is no file with that name.
 178 .TP
 179 .B GLOB_TILDE
 180 Carry out tilde expansion.
 181 If a tilde (\(aq~\(aq) is the only character in the pattern,
 182 or an initial tilde is followed immediately by a slash (\(aq/\(aq),
 183 then the home directory of the caller is substituted for
 184 the tilde.
 185 If an initial tilde is followed by a username (e.g., "~andrea/bin"),
 186 then the tilde and username are substituted by the home directory
 187 of that user.
 188 If the username is invalid, or the home directory cannot be
 189 determined, then no substitution is performed.
 190 .TP
 191 .B GLOB_TILDE_CHECK
 192 This provides behavior similar to that of
 193 .BR GLOB_TILDE .
 194 The difference is that if the username is invalid, or the
 195 home directory cannot be determined, then
 196 instead of using the pattern itself as the name,
 197 .BR glob ()
 198 returns
 199 .BR GLOB_NOMATCH
 200 to indicate an error.
 201 .TP
 202 .B GLOB_ONLYDIR
 203 This is a
 204 .I hint
 205 to
 206 .BR glob ()
 207 that the caller is interested only in directories that match the pattern.
 208 If the implementation can easily determine file-type information,
 209 then nondirectory files are not returned to the caller.
 210 However, the caller must still check that returned files
 211 are directories.
 212 (The purpose of this flag is merely to optimize performance when
 213 the caller is interested only in directories.)
 214 .PP
 215 If
 216 .I errfunc
 217 is not NULL,
 218 it will be called in case of an error with the arguments
 219 .IR epath ,
 220 a pointer to the path which failed, and
 221 .IR eerrno ,
 222 the value of
 223 .I errno
 224 as returned from one of the calls to
 225 .BR opendir (3),
 226 .BR readdir (3),
 227 or
 228 .BR stat (2).
 229 If
 230 .I errfunc
 231 returns nonzero, or if
 232 .B GLOB_ERR
 233 is set,
 234 .BR glob ()
 235 will terminate after the call to
 236 .IR errfunc .
 237 .PP
 238 Upon successful return,
 239 .I pglob\->gl_pathc
 240 contains the number of matched pathnames and
 241 .I pglob\->gl_pathv
 242 contains a pointer to the list of pointers to matched pathnames.
 243 The list of pointers is terminated by a NULL pointer.
 244 .PP
 245 It is possible to call
 246 .BR glob ()
 247 several times.
 248 In that case, the
 249 .B GLOB_APPEND
 250 flag has to be set in
 251 .I flags
 252 on the second and later invocations.
 253 .PP
 254 As a GNU extension,
 255 .I pglob\->gl_flags
 256 is set to the flags specified, \fBor\fRed with
 257 .B GLOB_MAGCHAR
 258 if any metacharacters were found.
 259 .SH RETURN VALUE
 260 On successful completion,
 261 .BR glob ()
 262 returns zero.
 263 Other possible returns are:
 264 .TP
 265 .B GLOB_NOSPACE
 266 for running out of memory,
 267 .TP
 268 .B GLOB_ABORTED
 269 for a read error, and
 270 .TP
 271 .B GLOB_NOMATCH
 272 for no found matches.
 273 .SH CONFORMING TO
 274 POSIX.2, POSIX.1-2001.
 275 .SH NOTES
 276 The structure elements
 277 .I gl_pathc
 278 and
 279 .I gl_offs
 280 are declared as
 281 .I size_t
 282 in glibc 2.1, as they should be according to POSIX.2,
 283 but are declared as
 284 .I int
 285 in libc4, libc5 and glibc 2.0.
 286 .SH BUGS
 287 The
 288 .BR glob ()
 289 function may fail due to failure of underlying function calls, such as
 290 .BR malloc (3)
 291 or
 292 .BR opendir (3).
 293 These will store their error code in
 294 .IR errno .
 295 .SH EXAMPLE
 296 One example of use is the following code, which simulates typing
 297 .sp
 298 .in +4n
 299 ls \-l *.c ../*.c
 300 .in
 301 .sp
 302 in the shell:
 303 .nf
 304 .in +4n
 305
 306 glob_t globbuf;
 307
 308 globbuf.gl_offs = 2;
 309 glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
 310 glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf);
 311 globbuf.gl_pathv[0] = "ls";
 312 globbuf.gl_pathv[1] = "\-l";
 313 execvp("ls", &globbuf.gl_pathv[0]);
 314 .in
 315 .fi
 316 .SH SEE ALSO
 317 .BR ls (1),
 318 .BR sh (1),
 319 .BR stat (2),
 320 .BR exec (3),
 321 .BR fnmatch (3),
 322 .BR malloc (3),
 323 .BR opendir (3),
 324 .BR readdir (3),
 325 .BR wordexp (3),
 326 .BR glob (7)