man3/glob.3

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