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  2016-10-08 "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 filesystem 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
 163 .BR {a,b} .
 164 Brace expressions can be nested.
 165 Thus, for example, specifying the pattern
 166 "{foo/{,cat,dog},bar}" would return the same results as four separate
 167 .BR glob ()
 168 calls using the strings:
 169 "foo/",
 170 "foo/cat",
 171 "foo/dog",
 172 and
 173 "bar".
 174 .TP
 175 .B GLOB_NOMAGIC
 176 If the pattern contains no metacharacters,
 177 then it should be returned as the sole matching word,
 178 even if there is no file with that name.
 179 .TP
 180 .B GLOB_TILDE
 181 Carry out tilde expansion.
 182 If a tilde (\(aq~\(aq) is the only character in the pattern,
 183 or an initial tilde is followed immediately by a slash (\(aq/\(aq),
 184 then the home directory of the caller is substituted for
 185 the tilde.
 186 If an initial tilde is followed by a username (e.g., "~andrea/bin"),
 187 then the tilde and username are substituted by the home directory
 188 of that user.
 189 If the username is invalid, or the home directory cannot be
 190 determined, then no substitution is performed.
 191 .TP
 192 .B GLOB_TILDE_CHECK
 193 This provides behavior similar to that of
 194 .BR GLOB_TILDE .
 195 The difference is that if the username is invalid, or the
 196 home directory cannot be determined, then
 197 instead of using the pattern itself as the name,
 198 .BR glob ()
 199 returns
 200 .BR GLOB_NOMATCH
 201 to indicate an error.
 202 .TP
 203 .B GLOB_ONLYDIR
 204 This is a
 205 .I hint
 206 to
 207 .BR glob ()
 208 that the caller is interested only in directories that match the pattern.
 209 If the implementation can easily determine file-type information,
 210 then nondirectory files are not returned to the caller.
 211 However, the caller must still check that returned files
 212 are directories.
 213 (The purpose of this flag is merely to optimize performance when
 214 the caller is interested only in directories.)
 215 .PP
 216 If
 217 .I errfunc
 218 is not NULL,
 219 it will be called in case of an error with the arguments
 220 .IR epath ,
 221 a pointer to the path which failed, and
 222 .IR eerrno ,
 223 the value of
 224 .I errno
 225 as returned from one of the calls to
 226 .BR opendir (3),
 227 .BR readdir (3),
 228 or
 229 .BR stat (2).
 230 If
 231 .I errfunc
 232 returns nonzero, or if
 233 .B GLOB_ERR
 234 is set,
 235 .BR glob ()
 236 will terminate after the call to
 237 .IR errfunc .
 238 .PP
 239 Upon successful return,
 240 .I pglob\->gl_pathc
 241 contains the number of matched pathnames and
 242 .I pglob\->gl_pathv
 243 contains a pointer to the list of pointers to matched pathnames.
 244 The list of pointers is terminated by a null pointer.
 245 .PP
 246 It is possible to call
 247 .BR glob ()
 248 several times.
 249 In that case, the
 250 .B GLOB_APPEND
 251 flag has to be set in
 252 .I flags
 253 on the second and later invocations.
 254 .PP
 255 As a GNU extension,
 256 .I pglob\->gl_flags
 257 is set to the flags specified,
 258 .BR or ed
 259 with
 260 .B GLOB_MAGCHAR
 261 if any metacharacters were found.
 262 .SH RETURN VALUE
 263 On successful completion,
 264 .BR glob ()
 265 returns zero.
 266 Other possible returns are:
 267 .TP
 268 .B GLOB_NOSPACE
 269 for running out of memory,
 270 .TP
 271 .B GLOB_ABORTED
 272 for a read error, and
 273 .TP
 274 .B GLOB_NOMATCH
 275 for no found matches.
 276 .SH ATTRIBUTES
 277 For an explanation of the terms used in this section, see
 278 .BR attributes (7).
 279 .TS
 280 allbox;
 281 lb lb lbw24
 282 l l l.
 283 Interface       Attribute       Value
 284 T{
 285 .BR glob ()
 286 T}      Thread safety   T{
 287 MT-Unsafe race:utent env
 288 .br
 289 sig:ALRM timer locale
 290 T}
 291 T{
 292 .BR globfree ()
 293 T}      Thread safety   MT-Safe
 294 .TE
 295
 296 In the above table,
 297 .I utent
 298 in
 299 .I race:utent
 300 signifies that if any of the functions
 301 .BR setutent (3),
 302 .BR getutent (3),
 303 or
 304 .BR endutent (3)
 305 are used in parallel in different threads of a program,
 306 then data races could occur.
 307 .BR glob ()
 308 calls those functions,
 309 so we use race:utent to remind users.
 310 .SH CONFORMING TO
 311 POSIX.1-2001, POSIX.1-2008, POSIX.2.
 312 .SH NOTES
 313 The structure elements
 314 .I gl_pathc
 315 and
 316 .I gl_offs
 317 are declared as
 318 .I size_t
 319 in glibc 2.1, as they should be according to POSIX.2,
 320 but are declared as
 321 .I int
 322 in glibc 2.0.
 323 .SH BUGS
 324 The
 325 .BR glob ()
 326 function may fail due to failure of underlying function calls, such as
 327 .BR malloc (3)
 328 or
 329 .BR opendir (3).
 330 These will store their error code in
 331 .IR errno .
 332 .SH EXAMPLE
 333 One example of use is the following code, which simulates typing
 334 .sp
 335 .in +4n
 336 ls \-l *.c ../*.c
 337 .in
 338 .sp
 339 in the shell:
 340 .nf
 341 .in +4n
 342
 343 glob_t globbuf;
 344
 345 globbuf.gl_offs = 2;
 346 glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
 347 glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf);
 348 globbuf.gl_pathv[0] = "ls";
 349 globbuf.gl_pathv[1] = "\-l";
 350 execvp("ls", &globbuf.gl_pathv[0]);
 351 .in
 352 .fi
 353 .SH SEE ALSO
 354 .BR ls (1),
 355 .BR sh (1),
 356 .BR stat (2),
 357 .BR exec (3),
 358 .BR fnmatch (3),
 359 .BR malloc (3),
 360 .BR opendir (3),
 361 .BR readdir (3),
 362 .BR wordexp (3),
 363 .BR glob (7)