+.\" Copyright (c) 1989 The Regents of the University of California.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to Berkeley by
+.\" Guido van Rossum.
+.\"
+.\" Redistribution and use in source and binary forms are permitted
+.\" provided that the above copyright notice and this paragraph are
+.\" duplicated in all such forms and that any documentation,
+.\" advertising materials, and other materials related to such
+.\" distribution and use acknowledge that the software was developed
+.\" by the University of California, Berkeley. The name of the
+.\" University may not be used to endorse or promote products derived
+.\" from this software without specific prior written permission.
+.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" @(#)glob.3 5.1 (Berkeley) %G%
+.\"
+.TH GLOB 3 ""
+.UC 7
+.SH NAME
+glob, globfree \- generate pathnames matching a pattern
+.SH SYNOPSIS
+.nf
+#include <glob.h>
+
+glob(const char *pattern, int flags,
+ const int (*errfunc)(char *, int), glob_t *pglob);
+
+void globfree(glob_t *pglob);
+.fi
+.SH DESCRIPTION
+.I Glob
+is a pathname generator that implements the rules for file name pattern
+matching used by the shell.
+.PP
+The include file
+.I glob.h
+defines the structure type
+.IR glob_t ,
+which contains at least the following fields:
+.sp
+.RS
+.nf
+.ta .5i +\w'char **gl_pathv;\0\0\0'u
+typedef struct {
+ int gl_pathc; /* count of paths matching pattern */
+ int gl_offs; /* reserved at beginning of gl_pathv */
+ char **gl_pathv; /* list of paths matching pattern */
+} glob_t;
+.fi
+.RE
+.PP
+The argument
+.I pattern
+is a pointer to a pathname pattern to be expanded.
+.I Glob
+matches all accessible pathnames against the pattern and creates
+a list of the pathnames that match.
+In order to have access to a pathname,
+.I glob
+requires search permission on every component of a path except the last
+and read permission on each directory of any filename component of
+.I pattern
+that contains any of the special characters ``*'', ``?'' or ``[''.
+.PP
+.I Glob
+stores the number of matched pathnames into the
+.I gl_pathc
+field, and a pointer to a list of pointers to pathnames into the
+.I gl_pathv
+field.
+The first pointer after the last pathname is NULL.
+If the pattern does not match any pathnames, the returned number of
+matched paths is set to zero.
+.PP
+It is the caller's responsibility to create the structure pointed to by
+.IR pglob .
+The
+.I glob
+function allocates other space as needed, including the memory pointed
+to by
+.IR gl_pathv .
+.PP
+The argument
+.I flags
+is used to modify the behavior of
+.IR glob .
+The value of
+.I flags
+is the bitwise inclusive OR of any of the following
+values defined in
+.IR glob.h :
+.TP
+GLOB_APPEND
+Append pathnames generated to the ones from a previous call (or calls)
+to
+.IR glob .
+The value of
+.I gl_pathc
+will be the total matches found by this call and the previous call(s).
+The pathnames are appended to, not merged with the pathnames returned by
+the previous call(s).
+Between calls, the caller must not change the setting of the
+GLOB_DOOFFS flag, nor change the value of
+.I gl_offs
+when
+GLOB_DOOFFS is set, nor (obviously) call
+.I globfree
+for
+.I pglob.
+.TP
+GLOB_DOOFFS
+Make use of the
+.I gl_offs
+field.
+If this flag is set,
+.I gl_offs
+is used to specify how many NULL pointers to prepend to the beginning
+of the
+.I gl_pathv
+field.
+In other words,
+.I gl_pathv
+will point to
+.I gl_offs
+NULL pointers,
+followed by
+.I gl_pathc
+pathname pointers, followed by a NULL pointer.
+.TP
+GLOB_ERR
+Causes
+.I glob
+to return when it encounters a directory that it cannot open or read.
+Ordinarily,
+.I glob
+continues to find matches.
+.TP
+GLOB_MARK
+Each pathname that is a directory that matches
+.I pattern
+has a slash
+appended.
+.TP
+GLOB_NOSORT
+By default, the pathnames are sorted in ascending ASCII order;
+this flag prevents that sorting (speeding up
+.IR glob ).
+.TP
+GLOB_NOCHECK
+If
+.I pattern
+does not match any pathname, then
+.I glob
+returns a list
+consisting of only
+.IR pattern ,
+and the number of matched pathnames is set to 1.
+If
+.I GLOB_QUOTE
+is set, its effect is present in the pattern returned.
+.TP
+GLOB_QUOTE
+Use the backslash (``\e'') character for quoting: every occurrence of
+a backslash followed by a character in the pattern is replaced by that
+character, avoiding any special interpretation of the character.
+.PP
+If, during the search, a directory is encountered that cannot be opened
+or read and
+.I errfunc
+is non-NULL,
+.I glob
+calls (*\fIerrfunc\fP)(\fIpath\fP, \fIerrno\fP).
+This may be unintuitive: a pattern like ``*/Makefile'' will try to
+.IR stat (2)
+``foo/Makefile'' even if ``foo'' is not a directory, resulting in a
+call to
+.IR errfunc .
+The error routine can suppress this action by testing for ENOENT and
+ENOTDIR; however, the GLOB_ERR flag will still cause an immediate
+return when this happens.
+.PP
+If
+.I errfunc
+returns non-zero,
+.I glob
+stops the scan and returns
+.I GLOB_ABEND
+after setting
+.I gl_pathc
+and
+.I gl_pathv
+to reflect any paths already matched.
+This also happens if an error is encountered and
+.I GLOB_ERR
+is set in
+.IR flags ,
+regardless of the return value of
+.IR errfunc ,
+if called.
+If
+.I GLOB_ERR
+is not set and either
+.I errfunc
+is NULL or
+.I errfunc
+returns zero, the error is ignored.
+.PP
+The
+.I globfree
+function frees any space associated with
+.I pglob
+from a previous call(s) to
+.IR glob .
+.SH RETURNS
+On successful completion,
+.I glob
+returns zero.
+The field
+.I gl_pathc
+returns the number of matched pathnames and
+the field
+.I gl_pathv
+contains a pointer to a NULL-terminated list of matched pathnames.
+However, if
+.I pglob->gl_pathc
+is zero, the contents of
+.I pglob->gl_pathv
+is undefined.
+.PP
+If
+.I glob
+terminates due to an error, it sets errno and returns one of the
+following non-zero constants, which are defined in the include
+file <glob.h>:
+.TP
+GLOB_NOSPACE
+An attempt to allocate memory failed.
+.TP
+GLOB_ABEND
+The scan was stopped because an error was encountered and either
+GLOB_ERR was set or (*\fIerrfunc\fR)() returned non-zero.
+.PP
+The arguments
+.I pglob->gl_pathc
+and
+.I pglob->gl_pathv
+are still set as specified above.
+.SH STANDARDS
+The
+.I glob
+function is expected to be POSIX 1003.2 compatible with the exception
+that the flag GLOB_QUOTE should not be used by applications striving
+for strict POSIX conformance.
+.SH EXAMPLE
+A rough equivalent of ``ls -l *.c *.h'' can be obtained with the
+following code:
+.sp
+.nf
+.RS
+glob_t g;
+
+g.gl_offs = 2;
+glob("*.c", GLOB_DOOFFS, NULL, &g);
+glob("*.h", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
+g.gl_pathv[0] = "ls";
+g.gl_pathv[1] = "-l";
+execvp("ls", g.gl_pathv);
+.RE
+.fi
+.SH SEE ALSO
+sh(1), fnmatch(3), wordexp(3), regexp(3)
+.SH BUGS
+Patterns longer than MAXPATHLEN may cause unchecked errors.
+.PP
+.I Glob
+may fail and set errno for any of the errors specified for the
+library routines
+.I stat (2),
+.I closedir (3),
+.I opendir (3),
+.I readdir (3),
+.I malloc (3),
+and
+.I free (3).
+
projects / unix-history / commitdiff