man3/glob.3

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