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  2021-03-22 "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 .PP
  41 .BI "int glob(const char *restrict " pattern ", int " flags ,
  42 .BI "         int (*" errfunc ")(const char *" epath ", int " eerrno ),
  43 .BI "         glob_t *restrict " pglob );
  44 .BI "void globfree(glob_t *" pglob );
  45 .fi
  46 .SH DESCRIPTION
  47 The
  48 .BR glob ()
  49 function searches for all the pathnames matching
  50 .I pattern
  51 according to the rules used by the shell (see
  52 .BR glob (7)).
  53 No tilde expansion or parameter substitution is done; if you want
  54 these, use
  55 .BR wordexp (3).
  56 .PP
  57 The
  58 .BR globfree ()
  59 function frees the dynamically allocated storage from an earlier call
  60 to
  61 .BR glob ().
  62 .PP
  63 The results of a
  64 .BR glob ()
  65 call are stored in the structure pointed to by
  66 .IR pglob .
  67 This structure is of type
  68 .I glob_t
  69 (declared in
  70 .IR <glob.h> )
  71 and includes the following elements defined by POSIX.2 (more may be
  72 present as an extension):
  73 .PP
  74 .in +4n
  75 .EX
  76 typedef struct {
  77     size_t   gl_pathc;    /* Count of paths matched so far  */
  78     char   **gl_pathv;    /* List of matched pathnames.  */
  79     size_t   gl_offs;     /* Slots to reserve in \fIgl_pathv\fP.  */
  80 } glob_t;
  81 .EE
  82 .in
  83 .PP
  84 Results are stored in dynamically allocated storage.
  85 .PP
  86 The argument
  87 .I flags
  88 is made up of the bitwise OR of zero or more the following symbolic
  89 constants, which modify the behavior of
  90 .BR glob ():
  91 .TP
  92 .B GLOB_ERR
  93 Return upon a read error (because a directory does not
  94 have read permission, for example).
  95 By default,
  96 .BR glob ()
  97 attempts carry on despite errors,
  98 reading all of the directories that it can.
  99 .TP
 100 .B GLOB_MARK
 101 Append a slash to each path which corresponds to a directory.
 102 .TP
 103 .B GLOB_NOSORT
 104 Don't sort the returned pathnames.
 105 The only reason to do this is to save processing time.
 106 By default, the returned pathnames are sorted.
 107 .TP
 108 .B GLOB_DOOFFS
 109 Reserve
 110 .I pglob\->gl_offs
 111 slots at the beginning of the list of strings in
 112 .IR pglob\->pathv .
 113 The reserved slots contain null pointers.
 114 .TP
 115 .B GLOB_NOCHECK
 116 If no pattern matches, return the original pattern.
 117 By default,
 118 .BR glob ()
 119 returns
 120 .B GLOB_NOMATCH
 121 if there are no matches.
 122 .TP
 123 .B GLOB_APPEND
 124 Append the results of this call to the vector of results
 125 returned by a previous call to
 126 .BR glob ().
 127 Do not set this flag on the first invocation of
 128 .BR glob ().
 129 .TP
 130 .B GLOB_NOESCAPE
 131 Don't allow backslash (\(aq\e\(aq) to be used as an escape
 132 character.
 133 Normally, a backslash can be used to quote the following character,
 134 providing a mechanism to turn off the special meaning
 135 metacharacters.
 136 .PP
 137 .I flags
 138 may also include any of the following, which are GNU
 139 extensions and not defined by POSIX.2:
 140 .TP
 141 .B GLOB_PERIOD
 142 Allow a leading period to be matched by metacharacters.
 143 By default, metacharacters can't match a leading period.
 144 .TP
 145 .B GLOB_ALTDIRFUNC
 146 Use alternative functions
 147 .IR pglob\->gl_closedir ,
 148 .IR pglob\->gl_readdir ,
 149 .IR pglob\->gl_opendir ,
 150 .IR pglob\->gl_lstat ", and"
 151 .I pglob\->gl_stat
 152 for filesystem access instead of the normal library
 153 functions.
 154 .TP
 155 .B GLOB_BRACE
 156 Expand
 157 .BR csh (1)
 158 style brace expressions of the form
 159 .BR {a,b} .
 160 Brace expressions can be nested.
 161 Thus, for example, specifying the pattern
 162 "{foo/{,cat,dog},bar}" would return the same results as four separate
 163 .BR glob ()
 164 calls using the strings:
 165 "foo/",
 166 "foo/cat",
 167 "foo/dog",
 168 and
 169 "bar".
 170 .TP
 171 .B GLOB_NOMAGIC
 172 If the pattern contains no metacharacters,
 173 then it should be returned as the sole matching word,
 174 even if there is no file with that name.
 175 .TP
 176 .B GLOB_TILDE
 177 Carry out tilde expansion.
 178 If a tilde (\(aq\(ti\(aq) is the only character in the pattern,
 179 or an initial tilde is followed immediately by a slash (\(aq/\(aq),
 180 then the home directory of the caller is substituted for
 181 the tilde.
 182 If an initial tilde is followed by a username (e.g., "\(tiandrea/bin"),
 183 then the tilde and username are substituted by the home directory
 184 of that user.
 185 If the username is invalid, or the home directory cannot be
 186 determined, then no substitution is performed.
 187 .TP
 188 .B GLOB_TILDE_CHECK
 189 This provides behavior similar to that of
 190 .BR GLOB_TILDE .
 191 The difference is that if the username is invalid, or the
 192 home directory cannot be determined, then
 193 instead of using the pattern itself as the name,
 194 .BR glob ()
 195 returns
 196 .BR GLOB_NOMATCH
 197 to indicate an error.
 198 .TP
 199 .B GLOB_ONLYDIR
 200 This is a
 201 .I hint
 202 to
 203 .BR glob ()
 204 that the caller is interested only in directories that match the pattern.
 205 If the implementation can easily determine file-type information,
 206 then nondirectory files are not returned to the caller.
 207 However, the caller must still check that returned files
 208 are directories.
 209 (The purpose of this flag is merely to optimize performance when
 210 the caller is interested only in directories.)
 211 .PP
 212 If
 213 .I errfunc
 214 is not NULL,
 215 it will be called in case of an error with the arguments
 216 .IR epath ,
 217 a pointer to the path which failed, and
 218 .IR eerrno ,
 219 the value of
 220 .I errno
 221 as returned from one of the calls to
 222 .BR opendir (3),
 223 .BR readdir (3),
 224 or
 225 .BR stat (2).
 226 If
 227 .I errfunc
 228 returns nonzero, or if
 229 .B GLOB_ERR
 230 is set,
 231 .BR glob ()
 232 will terminate after the call to
 233 .IR errfunc .
 234 .PP
 235 Upon successful return,
 236 .I pglob\->gl_pathc
 237 contains the number of matched pathnames and
 238 .I pglob\->gl_pathv
 239 contains a pointer to the list of pointers to matched pathnames.
 240 The list of pointers is terminated by a null pointer.
 241 .PP
 242 It is possible to call
 243 .BR glob ()
 244 several times.
 245 In that case, the
 246 .B GLOB_APPEND
 247 flag has to be set in
 248 .I flags
 249 on the second and later invocations.
 250 .PP
 251 As a GNU extension,
 252 .I pglob\->gl_flags
 253 is set to the flags specified,
 254 .BR or ed
 255 with
 256 .B GLOB_MAGCHAR
 257 if any metacharacters were found.
 258 .SH RETURN VALUE
 259 On successful completion,
 260 .BR glob ()
 261 returns zero.
 262 Other possible returns are:
 263 .TP
 264 .B GLOB_NOSPACE
 265 for running out of memory,
 266 .TP
 267 .B GLOB_ABORTED
 268 for a read error, and
 269 .TP
 270 .B GLOB_NOMATCH
 271 for no found matches.
 272 .SH ATTRIBUTES
 273 For an explanation of the terms used in this section, see
 274 .BR attributes (7).
 275 .ad l
 276 .nh
 277 .TS
 278 allbox;
 279 lb lb lbx
 280 l l l.
 281 Interface       Attribute       Value
 282 T{
 283 .BR glob ()
 284 T}      Thread safety   T{
 285 MT-Unsafe race:utent env
 286 sig:ALRM timer locale
 287 T}
 288 T{
 289 .BR globfree ()
 290 T}      Thread safety   MT-Safe
 291 .TE
 292 .hy
 293 .ad
 294 .sp 1
 295 In the above table,
 296 .I utent
 297 in
 298 .I race:utent
 299 signifies that if any of the functions
 300 .BR setutent (3),
 301 .BR getutent (3),
 302 or
 303 .BR endutent (3)
 304 are used in parallel in different threads of a program,
 305 then data races could occur.
 306 .BR glob ()
 307 calls those functions,
 308 so we use race:utent to remind users.
 309 .SH CONFORMING TO
 310 POSIX.1-2001, POSIX.1-2008, POSIX.2.
 311 .SH NOTES
 312 The structure elements
 313 .I gl_pathc
 314 and
 315 .I gl_offs
 316 are declared as
 317 .I size_t
 318 in glibc 2.1, as they should be according to POSIX.2,
 319 but are declared as
 320 .I int
 321 in glibc 2.0.
 322 .SH BUGS
 323 The
 324 .BR glob ()
 325 function may fail due to failure of underlying function calls, such as
 326 .BR malloc (3)
 327 or
 328 .BR opendir (3).
 329 These will store their error code in
 330 .IR errno .
 331 .SH EXAMPLES
 332 One example of use is the following code, which simulates typing
 333 .PP
 334 .in +4n
 335 .EX
 336 ls \-l *.c ../*.c
 337 .EE
 338 .in
 339 .PP
 340 in the shell:
 341 .PP
 342 .in +4n
 343 .EX
 344 glob_t globbuf;
 345
 346 globbuf.gl_offs = 2;
 347 glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
 348 glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf);
 349 globbuf.gl_pathv[0] = "ls";
 350 globbuf.gl_pathv[1] = "\-l";
 351 execvp("ls", &globbuf.gl_pathv[0]);
 352 .EE
 353 .in
 354 .SH SEE ALSO
 355 .BR ls (1),
 356 .BR sh (1),
 357 .BR stat (2),
 358 .BR exec (3),
 359 .BR fnmatch (3),
 360 .BR malloc (3),
 361 .BR opendir (3),
 362 .BR readdir (3),
 363 .BR wordexp (3),
 364 .BR glob (7)