Print this page
1097 glob(3c) needs to support non-POSIX options

Split Close
Expand all
Collapse all
          --- old/usr/src/man/man3c/glob.3c
          +++ new/usr/src/man/man3c/glob.3c
   1    1  '\" te
   2      -.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.  Portions Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved.
        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
   3    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
   4    6  .\" http://www.opengroup.org/bookstore/.
   5    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 +.\"
   6   40  .\"  This notice shall appear on any product containing this material.
   7   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.
   8   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.
   9   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]
  10   44  .TH GLOB 3C "Nov 1, 2003"
  11   45  .SH NAME
  12   46  glob, globfree \- generate path names matching a pattern
  13   47  .SH SYNOPSIS
  14   48  .LP
  15   49  .nf
↓ open down ↓ 35 lines elided ↑ open up ↑
  51   85  .in -2
  52   86  
  53   87  .SS "\fIpglob\fR Argument"
  54   88  .sp
  55   89  .LP
  56   90  The structure type \fBglob_t\fR is defined in the header \fB<glob.h>\fR and
  57   91  includes at least the following members:
  58   92  .sp
  59   93  .in +2
  60   94  .nf
  61      -size_t   gl_pathc;     /* count of paths matched by */
       95 +size_t   gl_pathc;     /* Total count of paths matched by */
  62   96                         /* 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 */
       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. */
  67  101  .fi
  68  102  .in -2
  69  103  
  70  104  .sp
  71  105  .LP
  72  106  The \fBglob()\fR function stores the number of matched path names into
  73  107  \fIpglob\(mi>\fR\fBgl_pathc\fR and a pointer to a list of pointers to path
  74  108  names into \fIpglob\(mi>\fR\fBgl_pathv.\fR The path names are in sort order as
  75  109  defined by the current setting of the  \fBLC_COLLATE\fR category. The first
  76  110  pointer after the last path name is a \fINULL\fR pointer. If the pattern does
↓ open down ↓ 80 lines elided ↑ open up ↑
 157  191  .na
 158  192  \fB\fBGLOB_NOSORT\fR\fR
 159  193  .ad
 160  194  .RS 17n
 161  195  Ordinarily, \fBglob()\fR sorts the matching path names according to the current
 162  196  setting of the \fBLC_COLLATE\fR category.  When this flag is used the order of
 163  197  path names returned is unspecified.
 164  198  .RE
 165  199  
 166  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
 167  311  .LP
 168  312  The \fBGLOB_APPEND\fR flag can be used to append a new set of path names to
 169  313  those found in a previous call to \fBglob()\fR. The following rules apply when
 170  314  two or more calls to \fBglob()\fR are made with the same value of \fIpglob\fR
 171  315  and without intervening calls to \fBglobfree()\fR:
 172  316  .RS +4
 173  317  .TP
 174  318  1.
 175  319  The first such call must not set \fBGLOB_APPEND.\fR All subsequent calls
 176  320  must set it.
↓ open down ↓ 53 lines elided ↑ open up ↑
 230  374  The \fIepath\fR argument is a pointer to the path that failed.
 231  375  .RE
 232  376  .RS +4
 233  377  .TP
 234  378  2.
 235  379  The \fIeerrno\fR argument is the value of \fIerrno\fR from the failure, as
 236  380  set by the \fBopendir\fR(3C), \fBreaddir\fR(3C) or \fBstat\fR(2) functions.
 237  381  (Other values may be used to report other errors not explicitly documented for
 238  382  those functions.)
 239  383  .RE
      384 +
 240  385  .sp
 241  386  .LP
 242      -The following constants are defined as error return values for \fBglob()\fR:
      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
 243  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
 244  400  .ne 2
 245  401  .na
 246      -\fB\fBGLOB_ABORTED\fR\fR
      402 +\fB\fBgl_pathc\fR\fR
 247  403  .ad
 248  404  .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.
      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.
 251  408  .RE
 252  409  
 253  410  .sp
 254  411  .ne 2
 255  412  .na
 256      -\fB\fBGLOB_NOMATCH\fR\fR
      413 +\fB\fBgl_matchc\fR\fR
 257  414  .ad
 258  415  .RS 16n
 259      -The pattern does not match any existing path name, and \fBGLOB_NOCHECK\fR was
 260      -not set in flags.
      416 +Contains the number of matched pathnames in the current
      417 +invocation of \fBglob()\fR.
 261  418  .RE
 262  419  
 263  420  .sp
 264  421  .ne 2
 265  422  .na
 266      -\fB\fBGLOG_NOSPACE\fR\fR
      423 +\fB\fBgl_flags\fR\fR
 267  424  .ad
 268  425  .RS 16n
 269      -An attempt to allocate memory failed.
      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.
 270  429  .RE
 271  430  
 272  431  .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
      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 +
 281  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
 282  454  .LP
 283      -The following values are returned by \fBglob()\fR:
      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 +
 284  458  .sp
 285  459  .ne 2
 286  460  .na
 287      -\fB\fB0\fR\fR
      461 +\fB\fBGLOB_ABORTED\fR\fR
 288  462  .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.
      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.
 295  466  .RE
 296  467  
 297  468  .sp
 298  469  .ne 2
 299  470  .na
 300      -\fB\fBnon-zero\fR\fR
      471 +\fB\fBGLOB_NOMATCH\fR\fR
 301  472  .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.
      473 +.RS 16n
      474 +The pattern does not match any existing path name, and \fBGLOB_NOCHECK\fR was
      475 +not set in flags.
 306  476  .RE
 307  477  
 308  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 +
 309  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
 310  502  The \fBglobfree()\fR function returns no value.
 311  503  .SH USAGE
 312  504  .sp
 313  505  .LP
 314  506  This function is not provided for the purpose of enabling utilities to perform
 315  507  path name expansion on their arguments, as this operation is performed by the
 316  508  shell, and utilities are explicitly not expected to redo this. Instead, it is
 317  509  provided for applications that need to do path name expansion on strings
 318  510  obtained from other sources, such as a pattern typed by a user or read from a
 319  511  file.
↓ open down ↓ 117 lines elided ↑ open up ↑
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX