contrib/tcsh/glob.3

   1 .\" Copyright (c) 1989 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Guido van Rossum.
   6 .\"
   7 .\" Redistribution and use in source and binary forms are permitted provided
   8 .\" that: (1) source distributions retain this entire copyright notice and
   9 .\" comment, and (2) distributions including binaries display the following
  10 .\" acknowledgement:  ``This product includes software developed by the
  11 .\" University of California, Berkeley and its contributors'' in the
  12 .\" documentation or other materials provided with the distribution and in
  13 .\" all advertising materials mentioning features or use of this software.
  14 .\" Neither the name of the University nor the names of its contributors may
  15 .\" be used to endorse or promote products derived from this software without
  16 .\" specific prior written permission.
  17 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  18 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  19 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  20 .\"
  21 .\"     @(#)glob.3      5.3 (Berkeley) 3/19/91
  22 .\"
  23 .TH GLOB 3 "March 19, 1991"
  24 .UC 7
  25 .SH NAME
  26 glob, globfree \- generate pathnames matching a pattern
  27 .SH SYNOPSIS
  28 .nf
  29 #include <glob.h>
  30
  31 glob(const char *pattern, int flags,
  32         const int (*errfunc)(char *, int), glob_t *pglob);
  33
  34 void globfree(glob_t *pglob);
  35 .fi
  36 .SH DESCRIPTION
  37 .I Glob
  38 is a pathname generator that implements the rules for file name pattern
  39 matching used by the shell.
  40 .PP
  41 The include file
  42 .I glob.h
  43 defines the structure type
  44 .IR glob_t ,
  45 which contains at least the following fields:
  46 .sp
  47 .RS
  48 .nf
  49 .ta .5i +\w'char **gl_pathv;\0\0\0'u
  50 typedef struct {
  51         int gl_pathc;           /* count of total paths so far */
  52         int gl_matchc;          /* count of paths matching pattern */
  53         int gl_offs;            /* reserved at beginning of gl_pathv */
  54         int gl_flags;           /* returned flags */
  55         char **gl_pathv;        /* list of paths matching pattern */
  56 } glob_t;
  57 .fi
  58 .RE
  59 .PP
  60 The argument
  61 .I pattern
  62 is a pointer to a pathname pattern to be expanded.
  63 .I Glob
  64 matches all accessible pathnames against the pattern and creates
  65 a list of the pathnames that match.
  66 In order to have access to a pathname,
  67 .I glob
  68 requires search permission on every component of a path except the last
  69 and read permission on each directory of any filename component of
  70 .I pattern
  71 that contains any of the special characters ``*'', ``?'' or ``[''.
  72 .PP
  73 .I Glob
  74 stores the number of matched pathnames into the
  75 .I gl_pathc
  76 field, and a pointer to a list of pointers to pathnames into the
  77 .I gl_pathv
  78 field.
  79 The first pointer after the last pathname is NULL.
  80 If the pattern does not match any pathnames, the returned number of
  81 matched paths is set to zero.
  82 .PP
  83 It is the caller's responsibility to create the structure pointed to by
  84 .IR pglob .
  85 The
  86 .I glob
  87 function allocates other space as needed, including the memory pointed
  88 to by
  89 .IR gl_pathv .
  90 .PP
  91 The argument
  92 .I flags
  93 is used to modify the behavior of
  94 .IR glob .
  95 The value of
  96 .I flags
  97 is the bitwise inclusive OR of any of the following
  98 values defined in
  99 .IR glob.h :
 100 .TP
 101 GLOB_APPEND
 102 Append pathnames generated to the ones from a previous call (or calls)
 103 to
 104 .IR glob .
 105 The value of
 106 .I gl_pathc
 107 will be the total matches found by this call and the previous call(s).
 108 The pathnames are appended to, not merged with the pathnames returned by
 109 the previous call(s).
 110 Between calls, the caller must not change the setting of the
 111 GLOB_DOOFFS flag, nor change the value of
 112 .I gl_offs
 113 when
 114 GLOB_DOOFFS is set, nor (obviously) call
 115 .I globfree
 116 for
 117 .I pglob.
 118 .TP
 119 GLOB_DOOFFS
 120 Make use of the
 121 .I gl_offs
 122 field.
 123 If this flag is set,
 124 .I gl_offs
 125 is used to specify how many NULL pointers to prepend to the beginning
 126 of the
 127 .I gl_pathv
 128 field.
 129 In other words,
 130 .I gl_pathv
 131 will point to
 132 .I gl_offs
 133 NULL pointers,
 134 followed by
 135 .I gl_pathc
 136 pathname pointers, followed by a NULL pointer.
 137 .TP
 138 GLOB_ERR
 139 Causes
 140 .I glob
 141 to return when it encounters a directory that it cannot open or read.
 142 Ordinarily,
 143 .I glob
 144 continues to find matches.
 145 .TP
 146 GLOB_MARK
 147 Each pathname that is a directory that matches
 148 .I pattern
 149 has a slash
 150 appended.
 151 .TP
 152 GLOB_NOSORT
 153 By default, the pathnames are sorted in ascending ASCII order;
 154 this flag prevents that sorting (speeding up
 155 .IR glob ).
 156 .TP
 157 GLOB_NOCHECK
 158 If
 159 .I pattern
 160 does not match any pathname, then
 161 .I glob
 162 returns a list
 163 consisting of only
 164 .IR pattern ,
 165 with the number of total pathnames is set to 1, and the number of matched
 166 pathnames set to 0.
 167 If
 168 .I GLOB_QUOTE
 169 is set, its effect is present in the pattern returned.
 170 .TP
 171 GLOB_QUOTE
 172 Use the backslash (``\e'') character for quoting: every occurrence of
 173 a backslash followed by a character in the pattern is replaced by that
 174 character, avoiding any special interpretation of the character.
 175 .TP
 176 GLOB_NOMAGIC
 177 Is the same as GLOB_NOCHECK but it only appends the
 178 .IR pattern
 179 if it does not contain any of the special characters ``*'', ``?'' or ``[''.
 180 GLOB_NOMAGIC is used to simplify implementing the globbing behavior in
 181 .IR csh(1).
 182 .PP
 183 If, during the search, a directory is encountered that cannot be opened
 184 or read and
 185 .I errfunc
 186 is non-NULL,
 187 .I glob
 188 calls (*\fIerrfunc\fP)(\fIpath\fP, \fIerrno\fP).
 189 This may be unintuitive: a pattern like ``*/Makefile'' will try to
 190 .IR stat (2)
 191 ``foo/Makefile'' even if ``foo'' is not a directory, resulting in a
 192 call to
 193 .IR errfunc .
 194 The error routine can suppress this action by testing for ENOENT and
 195 ENOTDIR; however, the GLOB_ERR flag will still cause an immediate
 196 return when this happens.
 197 .PP
 198 If
 199 .I errfunc
 200 returns non-zero,
 201 .I glob
 202 stops the scan and returns
 203 .I GLOB_ABEND
 204 after setting
 205 .I gl_pathc
 206 and
 207 .I gl_pathv
 208 to reflect any paths already matched.
 209 This also happens if an error is encountered and
 210 .I GLOB_ERR
 211 is set in
 212 .IR flags ,
 213 regardless of the return value of
 214 .IR errfunc ,
 215 if called.
 216 If
 217 .I GLOB_ERR
 218 is not set and either
 219 .I errfunc
 220 is NULL or
 221 .I errfunc
 222 returns zero, the error is ignored.
 223 .PP
 224 The
 225 .I globfree
 226 function frees any space associated with
 227 .I pglob
 228 from a previous call(s) to
 229 .IR glob .
 230 .SH RETURNS
 231 On successful completion,
 232 .I glob
 233 returns zero.
 234 In addition the fields of
 235 .I pglob
 236 contain the values described below:
 237 .TP
 238 .I gl_pathc
 239 contains the total number of matched pathnames so far.
 240 This includes other matches from previous invocations of
 241 .I glob
 242 if
 243 .I GLOB_APPEND
 244 was specified.
 245 .TP
 246 .I gl_matchc
 247 contains the number of matched pathnames in the current invocation of
 248 .I glob.
 249 .TP
 250 .I gl_flags
 251 contains a copy of the
 252 .I flags
 253 parameter with the bit GLOB_MAGCHAR set if
 254 .I pattern
 255 contained any of the special characters ``*'', ``?'' or ``['', cleared
 256 if not.
 257 .TP
 258 .I gl_pathv
 259 contains a pointer to a NULL-terminated list of matched pathnames.
 260 However, if
 261 .I gl_pathc
 262 is zero, the contents of
 263 .I gl_pathv
 264 are undefined.
 265 .PP
 266 If
 267 .I glob
 268 terminates due to an error, it sets errno and returns one of the
 269 following non-zero constants, which are defined in the include
 270 file <glob.h>:
 271 .TP
 272 GLOB_NOSPACE
 273 An attempt to allocate memory failed.
 274 .TP
 275 GLOB_ABEND
 276 The scan was stopped because an error was encountered and either
 277 GLOB_ERR was set or (*\fIerrfunc\fR)() returned non-zero.
 278 .PP
 279 The arguments
 280 .I pglob->gl_pathc
 281 and
 282 .I pglob->gl_pathv
 283 are still set as specified above.
 284 .SH STANDARDS
 285 The
 286 .I glob
 287 function is expected to be POSIX 1003.2 compatible with the exception
 288 that the flag
 289 .I GLOB_QUOTE
 290 and the fields
 291 .I gl_matchc
 292 and
 293 .I gl_flags
 294 should not be used by applications striving for strict POSIX conformance.
 295 .SH EXAMPLE
 296 A rough equivalent of ``ls -l *.c *.h'' can be obtained with the
 297 following code:
 298 .sp
 299 .nf
 300 .RS
 301 glob_t g;
 302
 303 g.gl_offs = 2;
 304 glob("*.c", GLOB_DOOFFS, NULL, &g);
 305 glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
 306 g.gl_pathv[0] = "ls";
 307 g.gl_pathv[1] = "-l";
 308 execvp("ls", g.gl_pathv);
 309 .RE
 310 .fi
 311 .SH SEE ALSO
 312 sh(1), fnmatch(3), wordexp(3), regexp(3)
 313 .SH BUGS
 314 Patterns longer than MAXPATHLEN may cause unchecked errors.
 315 .PP
 316 .I Glob
 317 may fail and set errno for any of the errors specified for the
 318 library routines
 319 .I stat (2),
 320 .I closedir (3),
 321 .I opendir (3),
 322 .I readdir (3),
 323 .I malloc (3),
 324 and
 325 .I free (3).
 326