Print this page
1097 glob(3c) needs to support non-POSIX options
   1 '\" te
   2 .\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.  Portions Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved.


   3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   4 .\" http://www.opengroup.org/bookstore/.
   5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
































   6 .\"  This notice shall appear on any product containing this material.
   7 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   9 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  10 .TH GLOB 3C "Nov 1, 2003"
  11 .SH NAME
  12 glob, globfree \- generate path names matching a pattern
  13 .SH SYNOPSIS
  14 .LP
  15 .nf
  16 #include <glob.h>
  17 
  18 \fBint\fR \fBglob\fR(\fBconst char *restrict\fR \fIpattern\fR, \fBint\fR \fIflags\fR,
  19      \fBint(*\fR\fIerrfunc\fR)(const char *\fIepath\fR, int \fIeerrno)\fR,
  20      \fBglob_t *restrict\fR \fIpglob\fR);
  21 .fi
  22 
  23 .LP
  24 .nf
  25 \fBvoid\fR \fBglobfree\fR(\fBglob_t *\fR\fIpglob\fR);


  41 pattern and develops a list of all path names that match. In order to have
  42 access to a path name, \fBglob()\fR requires search permission on every
  43 component of a path except the last, and read permission on each directory of
  44 any filename component of \fIpattern\fR that contains any of the following
  45 special characters:
  46 .sp
  47 .in +2
  48 .nf
  49 *        ?        [
  50 .fi
  51 .in -2
  52 
  53 .SS "\fIpglob\fR Argument"
  54 .sp
  55 .LP
  56 The structure type \fBglob_t\fR is defined in the header \fB<glob.h>\fR and
  57 includes at least the following members:
  58 .sp
  59 .in +2
  60 .nf
  61 size_t   gl_pathc;     /* count of paths matched by */
  62                        /* pattern */
  63 char     **gl_pathv;   /* pointer to list of matched */
  64                        /* path names */
  65 size_t   gl_offs;      /* slots to reserve at beginning */
  66                        /* of gl_pathv */
  67 .fi
  68 .in -2
  69 
  70 .sp
  71 .LP
  72 The \fBglob()\fR function stores the number of matched path names into
  73 \fIpglob\(mi>\fR\fBgl_pathc\fR and a pointer to a list of pointers to path
  74 names into \fIpglob\(mi>\fR\fBgl_pathv.\fR The path names are in sort order as
  75 defined by the current setting of the  \fBLC_COLLATE\fR category. The first
  76 pointer after the last path name is a \fINULL\fR pointer. If the pattern does
  77 not match any path names, the returned number of matched paths is set to 0, and
  78 the contents of \fIpglob\(mi>\fR\fBgl_pathv\fR are implementation-dependent.
  79 .sp
  80 .LP
  81 It is the caller's responsibility to create the structure pointed to by
  82 \fIpglob\fR. The \fBglob()\fR function allocates other space as needed,
  83 including the memory pointed to by \fBgl_pathv\fR. The \fBglobfree()\fR
  84 function frees any space associated with \fIpglob\fR from a previous call to
  85 \fBglob()\fR.
  86 .SS "\fIflags\fR Argument"


 147 .ne 2
 148 .na
 149 \fB\fBGLOB_NOESCAPE\fR\fR
 150 .ad
 151 .RS 17n
 152 Disable backslash escaping.
 153 .RE
 154 
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBGLOB_NOSORT\fR\fR
 159 .ad
 160 .RS 17n
 161 Ordinarily, \fBglob()\fR sorts the matching path names according to the current
 162 setting of the \fBLC_COLLATE\fR category.  When this flag is used the order of
 163 path names returned is unspecified.
 164 .RE
 165 
 166 .sp














































































































 167 .LP
 168 The \fBGLOB_APPEND\fR flag can be used to append a new set of path names to
 169 those found in a previous call to \fBglob()\fR. The following rules apply when
 170 two or more calls to \fBglob()\fR are made with the same value of \fIpglob\fR
 171 and without intervening calls to \fBglobfree()\fR:
 172 .RS +4
 173 .TP
 174 1.
 175 The first such call must not set \fBGLOB_APPEND.\fR All subsequent calls
 176 must set it.
 177 .RE
 178 .RS +4
 179 .TP
 180 2.
 181 All the calls must set \fBGLOB_DOOFFS,\fR or all must not set it.
 182 .RE
 183 .RS +4
 184 .TP
 185 3.
 186 After the second call, \fIpglob\(mi>\fR\fBgl_pathv\fR points to a list


 220 .RE
 221 .SS "\fIerrfunc\fR and \fIepath\fR Arguments"
 222 .sp
 223 .LP
 224 If, during the search, a directory is encountered that cannot be opened or read
 225 and \fIerrfunc\fR is not a \fINULL\fR pointer, \fBglob()\fR calls
 226 \fB(\fR\fI*errfunc\fR\fB)\fR with two arguments:
 227 .RS +4
 228 .TP
 229 1.
 230 The \fIepath\fR argument is a pointer to the path that failed.
 231 .RE
 232 .RS +4
 233 .TP
 234 2.
 235 The \fIeerrno\fR argument is the value of \fIerrno\fR from the failure, as
 236 set by the \fBopendir\fR(3C), \fBreaddir\fR(3C) or \fBstat\fR(2) functions.
 237 (Other values may be used to report other errors not explicitly documented for
 238 those functions.)
 239 .RE

 240 .sp
 241 .LP
 242 The following constants are defined as error return values for \fBglob()\fR:






 243 .sp





 244 .ne 2
 245 .na
 246 \fB\fBGLOB_ABORTED\fR\fR
 247 .ad
 248 .RS 16n
 249 The scan was stopped because \fBGLOB_ERR\fR was set or
 250 \fB(\fR\fI*errfunc\fR\fB)\fR returned non-zero.

 251 .RE
 252 
 253 .sp
 254 .ne 2
 255 .na
 256 \fB\fBGLOB_NOMATCH\fR\fR
 257 .ad
 258 .RS 16n
 259 The pattern does not match any existing path name, and \fBGLOB_NOCHECK\fR was
 260 not set in flags.
 261 .RE
 262 
 263 .sp
 264 .ne 2
 265 .na
 266 \fB\fBGLOG_NOSPACE\fR\fR
 267 .ad
 268 .RS 16n
 269 An attempt to allocate memory failed.


 270 .RE
 271 
 272 .sp
 273 .LP
 274 If \fB(\fR\fI*errfunc\fR\fB)\fR is called and returns non-zero, or if the
 275 \fBGLOB_ERR\fR flag is set in \fIflags\fR, \fBglob()\fR stops the scan and
 276 returns \fBGLOB_ABORTED\fR after setting \fIgl_pathc\fR and \fIgl_pathv\fR in
 277 \fIpglob\fR to reflect the paths already scanned. If \fBGLOB_ERR\fR is not set
 278 and either \fIerrfunc\fR is a \fINULL\fR pointer or
 279 \fB(\fR\fI*errfunc\fR\fB)\fR returns 0, the error is ignored.
 280 .SH RETURN VALUES


 281 .sp











 282 .LP
 283 The following values are returned by \fBglob()\fR:


 284 .sp
 285 .ne 2
 286 .na
 287 \fB\fB0\fR\fR
 288 .ad
 289 .RS 12n
 290 Successful completion. The argument \fIpglob\(mi>\fR\fBgl_pathc\fR returns the
 291 number of matched path names and the argument \fIpglob\(mi>\fR\fBgl_pathv\fR
 292 contains a pointer to a null-terminated list of matched and sorted path names.
 293 However, if \fIpglob\(mi>\fR\fBgl_pathc\fR is 0, the content of
 294 \fIpglob\(mi>\fR\fBgl_pathv\fR is undefined.
 295 .RE
 296 
 297 .sp
 298 .ne 2
 299 .na
 300 \fB\fBnon-zero\fR\fR
 301 .ad
 302 .RS 12n
 303 An error has occurred. Non-zero constants are defined in <\fBglob.h\fR>. The
 304 arguments \fIpglob\(mi>\fR\fBgl_pathc\fR and \fIpglob\(mi>\fR\fBgl_pathv\fR are
 305 still set as defined above.
 306 .RE
 307 
 308 .sp


















 309 .LP




 310 The \fBglobfree()\fR function returns no value.
 311 .SH USAGE
 312 .sp
 313 .LP
 314 This function is not provided for the purpose of enabling utilities to perform
 315 path name expansion on their arguments, as this operation is performed by the
 316 shell, and utilities are explicitly not expected to redo this. Instead, it is
 317 provided for applications that need to do path name expansion on strings
 318 obtained from other sources, such as a pattern typed by a user or read from a
 319 file.
 320 .sp
 321 .LP
 322 If a utility needs to see if a path name matches a given pattern, it can use
 323 \fBfnmatch\fR(3C).
 324 .sp
 325 .LP
 326 Note that \fBgl_pathc\fR and \fBgl_pathv\fR have meaning even if \fBglob()\fR
 327 fails. This allows \fBglob()\fR to report partial results in the event of an
 328 error. However, if \fBgl_pathc\fR is 0, \fBgl_pathv\fR is unspecified even if
 329 \fBglob()\fR did not return an error.


   1 '\" te
   2 .\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
   3 .\" Portions Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved.
   4 .\" Portions Copyright (c) 2012, Gary Mills
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   6 .\" http://www.opengroup.org/bookstore/.
   7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   8 .\"
   9 .\" $OpenBSD: glob.3,v 1.30 2012/01/20 07:09:42 tedu Exp $
  10 .\"
  11 .\" Copyright (c) 1989, 1991, 1993, 1994
  12 .\" The Regents of the University of California.  All rights reserved.
  13 .\"
  14 .\" This code is derived from software contributed to Berkeley by
  15 .\" Guido van Rossum.
  16 .\" Redistribution and use in source and binary forms, with or without
  17 .\" modification, are permitted provided that the following conditions
  18 .\" are met:
  19 .\" 1. Redistributions of source code must retain the above copyright
  20 .\"    notice, this list of conditions and the following disclaimer.
  21 .\" 2. Redistributions in binary form must reproduce the above copyright
  22 .\"    notice, this list of conditions and the following disclaimer in the
  23 .\"    documentation and/or other materials provided with the distribution.
  24 .\" 3. Neither the name of the University nor the names of its contributors
  25 .\"    may be used to endorse or promote products derived from this software
  26 .\"    without specific prior written permission.
  27 .\"
  28 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  29 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  30 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  31 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  32 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  33 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  34 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  36 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  37 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  38 .\" SUCH DAMAGE.
  39 .\"
  40 .\"  This notice shall appear on any product containing this material.
  41 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
  42 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  43 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  44 .TH GLOB 3C "Nov 1, 2003"
  45 .SH NAME
  46 glob, globfree \- generate path names matching a pattern
  47 .SH SYNOPSIS
  48 .LP
  49 .nf
  50 #include <glob.h>
  51 
  52 \fBint\fR \fBglob\fR(\fBconst char *restrict\fR \fIpattern\fR, \fBint\fR \fIflags\fR,
  53      \fBint(*\fR\fIerrfunc\fR)(const char *\fIepath\fR, int \fIeerrno)\fR,
  54      \fBglob_t *restrict\fR \fIpglob\fR);
  55 .fi
  56 
  57 .LP
  58 .nf
  59 \fBvoid\fR \fBglobfree\fR(\fBglob_t *\fR\fIpglob\fR);


  75 pattern and develops a list of all path names that match. In order to have
  76 access to a path name, \fBglob()\fR requires search permission on every
  77 component of a path except the last, and read permission on each directory of
  78 any filename component of \fIpattern\fR that contains any of the following
  79 special characters:
  80 .sp
  81 .in +2
  82 .nf
  83 *        ?        [
  84 .fi
  85 .in -2
  86 
  87 .SS "\fIpglob\fR Argument"
  88 .sp
  89 .LP
  90 The structure type \fBglob_t\fR is defined in the header \fB<glob.h>\fR and
  91 includes at least the following members:
  92 .sp
  93 .in +2
  94 .nf
  95 size_t   gl_pathc;     /* Total count of paths matched by */
  96                        /* pattern */
  97 char     **gl_pathv;   /* List of matched path names */
  98 size_t   gl_offs;      /* # of slots reserved in gl_pathv */
  99 int      gl_matchc;    /* Count of paths matching pattern. */
 100 int      gl_flags;     /* Copy of flags parameter to glob. */
 101 .fi
 102 .in -2
 103 
 104 .sp
 105 .LP
 106 The \fBglob()\fR function stores the number of matched path names into
 107 \fIpglob\(mi>\fR\fBgl_pathc\fR and a pointer to a list of pointers to path
 108 names into \fIpglob\(mi>\fR\fBgl_pathv.\fR The path names are in sort order as
 109 defined by the current setting of the  \fBLC_COLLATE\fR category. The first
 110 pointer after the last path name is a \fINULL\fR pointer. If the pattern does
 111 not match any path names, the returned number of matched paths is set to 0, and
 112 the contents of \fIpglob\(mi>\fR\fBgl_pathv\fR are implementation-dependent.
 113 .sp
 114 .LP
 115 It is the caller's responsibility to create the structure pointed to by
 116 \fIpglob\fR. The \fBglob()\fR function allocates other space as needed,
 117 including the memory pointed to by \fBgl_pathv\fR. The \fBglobfree()\fR
 118 function frees any space associated with \fIpglob\fR from a previous call to
 119 \fBglob()\fR.
 120 .SS "\fIflags\fR Argument"


 181 .ne 2
 182 .na
 183 \fB\fBGLOB_NOESCAPE\fR\fR
 184 .ad
 185 .RS 17n
 186 Disable backslash escaping.
 187 .RE
 188 
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fBGLOB_NOSORT\fR\fR
 193 .ad
 194 .RS 17n
 195 Ordinarily, \fBglob()\fR sorts the matching path names according to the current
 196 setting of the \fBLC_COLLATE\fR category.  When this flag is used the order of
 197 path names returned is unspecified.
 198 .RE
 199 
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fBGLOB_ALTDIRFUNC\fR\fR
 204 .ad
 205 .RS 17n
 206 The following additional fields in the \fIpglob\fR structure
 207 have been initialized with alternate functions for
 208 \fBglob()\fR to use to open, read, and close directories and
 209 to get stat information on names found in those directories:
 210 .sp
 211 .nf
 212 DIR *(*gl_opendir)(const char *);
 213 struct dirent *(*gl_readdir)(DIR *);
 214 void (*gl_closedir)(DIR *);
 215 int (*gl_lstat)(const char *, struct stat *);
 216 int (*gl_stat)(const char *, struct stat *);
 217 .fi
 218 .sp
 219 This extension is provided to allow programs such as
 220 \fBufsrestore\fR(1M) to provide globbing from directories stored
 221 on tape.
 222 .RE
 223 
 224 .sp
 225 .ne 2
 226 .na
 227 \fB\fBGLOB_BRACE\fR\fR
 228 .ad
 229 .RS 17n
 230 Pre-process the pattern string to expand `{pat,pat,...}'
 231 strings like \fBcsh\fR(1).  The pattern `{}' is left unexpanded
 232 for historical reasons.  (\fBcsh\fR(1) does the same thing
 233 to ease typing of \fBfind\fR(1) patterns.)
 234 .RE
 235 
 236 .sp
 237 .ne 2
 238 .na
 239 \fB\fBGLOB_MAGCHAR\fR\fR
 240 .ad
 241 .RS 17n
 242 Set by the \fBglob()\fR function if the pattern included globbing
 243 characters.  See the description of the usage of
 244 the \fBgl_matchc\fR structure member for more details.
 245 .RE
 246 
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fBGLOB_NOMAGIC\fR\fR
 251 .ad
 252 .RS 17n
 253 Is the same as \fBGLOB_NOCHECK\fR but it only appends the
 254 pattern if it does not contain any of the special characters
 255 `*', `?', or `['.  \fBGLOB_NOMAGIC\fR is provided to
 256 simplify implementing the historic \fBcsh\fR(1) globbing behavior
 257 and should probably not be used anywhere else.
 258 .RE
 259 
 260 .sp
 261 .ne 2
 262 .na
 263 \fB\fBGLOB_QUOTE\fR\fR
 264 .ad
 265 .RS 17n
 266 This option has no effect and is included for backwards
 267 compatibility with older sources.
 268 .RE
 269 
 270 .sp
 271 .ne 2
 272 .na
 273 \fB\fBGLOB_TILDE\fR\fR
 274 .ad
 275 .RS 17n
 276 Expand patterns that start with `~' to user name home
 277 directories.
 278 .RE
 279 
 280 .sp
 281 .ne 2
 282 .na
 283 \fB\fBGLOB_LIMIT\fR\fR
 284 .ad
 285 .RS 17n
 286 Limit the amount of memory used by matches to \fIARG_MAX\fR.
 287 This option should be set for programs that can be coerced
 288 to a denial of service attack via patterns that
 289 expand to a very large number of matches, such as a long
 290 string of `*/../*/..'.
 291 .RE
 292 
 293 .sp
 294 .ne 2
 295 .na
 296 \fB\fBGLOB_KEEPSTAT\fR\fR
 297 .ad
 298 .RS 17n
 299 Retain a copy of the \fBstat\fR(2) information retrieved for
 300 matching paths in the gl_statv array:
 301 .sp
 302 .nf
 303 struct stat **gl_statv;
 304 .fi
 305 .sp
 306 This option may be used to avoid \fBlstat\fR(2) lookups in
 307 cases where they are expensive.
 308 .RE
 309 
 310 .sp
 311 .LP
 312 The \fBGLOB_APPEND\fR flag can be used to append a new set of path names to
 313 those found in a previous call to \fBglob()\fR. The following rules apply when
 314 two or more calls to \fBglob()\fR are made with the same value of \fIpglob\fR
 315 and without intervening calls to \fBglobfree()\fR:
 316 .RS +4
 317 .TP
 318 1.
 319 The first such call must not set \fBGLOB_APPEND.\fR All subsequent calls
 320 must set it.
 321 .RE
 322 .RS +4
 323 .TP
 324 2.
 325 All the calls must set \fBGLOB_DOOFFS,\fR or all must not set it.
 326 .RE
 327 .RS +4
 328 .TP
 329 3.
 330 After the second call, \fIpglob\(mi>\fR\fBgl_pathv\fR points to a list


 364 .RE
 365 .SS "\fIerrfunc\fR and \fIepath\fR Arguments"
 366 .sp
 367 .LP
 368 If, during the search, a directory is encountered that cannot be opened or read
 369 and \fIerrfunc\fR is not a \fINULL\fR pointer, \fBglob()\fR calls
 370 \fB(\fR\fI*errfunc\fR\fB)\fR with two arguments:
 371 .RS +4
 372 .TP
 373 1.
 374 The \fIepath\fR argument is a pointer to the path that failed.
 375 .RE
 376 .RS +4
 377 .TP
 378 2.
 379 The \fIeerrno\fR argument is the value of \fIerrno\fR from the failure, as
 380 set by the \fBopendir\fR(3C), \fBreaddir\fR(3C) or \fBstat\fR(2) functions.
 381 (Other values may be used to report other errors not explicitly documented for
 382 those functions.)
 383 .RE
 384 
 385 .sp
 386 .LP
 387 If \fB(\fR\fI*errfunc\fR\fB)\fR is called and returns non-zero, or if the
 388 \fBGLOB_ERR\fR flag is set in \fIflags\fR, \fBglob()\fR stops the scan and
 389 returns \fBGLOB_ABORTED\fR after setting \fIgl_pathc\fR and \fIgl_pathv\fR in
 390 \fIpglob\fR to reflect the paths already scanned. If \fBGLOB_ERR\fR is not set
 391 and either \fIerrfunc\fR is a \fINULL\fR pointer or
 392 \fB(\fR\fI*errfunc\fR\fB)\fR returns 0, the error is ignored.
 393 .SH RETURN VALUES
 394 .sp
 395 .LP
 396 On successful completion, \fBglob()\fR returns zero.
 397 In addition the fields of pglob contain the values described below:
 398 
 399 .sp
 400 .ne 2
 401 .na
 402 \fB\fBgl_pathc\fR\fR
 403 .ad
 404 .RS 16n
 405 Contains the total number of matched pathnames so far.
 406 This includes other matches from previous invocations of
 407 \fBglob()\fR if \fBGLOB_APPEND\fR was specified.
 408 .RE
 409 
 410 .sp
 411 .ne 2
 412 .na
 413 \fB\fBgl_matchc\fR\fR
 414 .ad
 415 .RS 16n
 416 Contains the number of matched pathnames in the current
 417 invocation of \fBglob()\fR.
 418 .RE
 419 
 420 .sp
 421 .ne 2
 422 .na
 423 \fB\fBgl_flags\fR\fR
 424 .ad
 425 .RS 16n
 426 Contains a copy of the flags parameter with the bit
 427 \fBGLOB_MAGCHAR\fR set if pattern contained any of the special
 428 characters `*', `?', or `[', cleared if not.
 429 .RE
 430 
 431 .sp
 432 .ne 2
 433 .na
 434 \fB\fBgl_pathv\fR\fR
 435 .ad
 436 .RS 16n
 437 Contains a pointer to a null-terminated list of matched
 438 pathnames.  However, if \fBgl_pathc\fR is zero, the contents of
 439 \fBgl_pathv\fR are undefined.
 440 .RE
 441 
 442 .sp
 443 .ne 2
 444 .na
 445 \fB\fBgl_statv\fR\fR
 446 .ad
 447 .RS 16n
 448 If the \fBGLOB_KEEPSTAT\fR flag was set, \fBgl_statv\fR contains a
 449 pointer to a null-terminated list of matched \fBstat\fR(2)
 450 objects corresponding to the paths in \fBgl_pathc\fR.
 451 .RE
 452 
 453 .sp
 454 .LP
 455 If \fBglob()\fR terminates due to an error, it sets \fBerrno\fR and
 456 returns one of the following non-zero constants. defined in <\fBglob.h\fR>:
 457 
 458 .sp
 459 .ne 2
 460 .na
 461 \fB\fBGLOB_ABORTED\fR\fR
 462 .ad
 463 .RS 16n
 464 The scan was stopped because \fBGLOB_ERR\fR was set or
 465 \fB(\fR\fI*errfunc\fR\fB)\fR returned non-zero.



 466 .RE
 467 
 468 .sp
 469 .ne 2
 470 .na
 471 \fB\fBGLOB_NOMATCH\fR\fR
 472 .ad
 473 .RS 16n
 474 The pattern does not match any existing path name, and \fBGLOB_NOCHECK\fR was
 475 not set in flags.

 476 .RE
 477 
 478 .sp
 479 .ne 2
 480 .na
 481 \fB\fBGLOB_NOSPACE\fR\fR
 482 .ad
 483 .RS 16n
 484 An attempt to allocate memory failed.
 485 .RE
 486 
 487 .sp
 488 .ne 2
 489 .na
 490 \fB\fBGLOB_NOSYS\fR\fR
 491 .ad
 492 .RS 16n
 493 The requested function is not supported by this version of
 494 \fBglob()\fR.
 495 .RE
 496 
 497 .LP
 498 The arguments \fIpglob\(mi>\fR\fBgl_pathc\fR and \fIpglob\(mi>\fR\fBgl_pathv\fR are still set as
 499 specified above.
 500 .sp
 501 .LP
 502 The \fBglobfree()\fR function returns no value.
 503 .SH USAGE
 504 .sp
 505 .LP
 506 This function is not provided for the purpose of enabling utilities to perform
 507 path name expansion on their arguments, as this operation is performed by the
 508 shell, and utilities are explicitly not expected to redo this. Instead, it is
 509 provided for applications that need to do path name expansion on strings
 510 obtained from other sources, such as a pattern typed by a user or read from a
 511 file.
 512 .sp
 513 .LP
 514 If a utility needs to see if a path name matches a given pattern, it can use
 515 \fBfnmatch\fR(3C).
 516 .sp
 517 .LP
 518 Note that \fBgl_pathc\fR and \fBgl_pathv\fR have meaning even if \fBglob()\fR
 519 fails. This allows \fBglob()\fR to report partial results in the event of an
 520 error. However, if \fBgl_pathc\fR is 0, \fBgl_pathv\fR is unspecified even if
 521 \fBglob()\fR did not return an error.