508 lines
11 KiB
HTML
508 lines
11 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of GLOB</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>GLOB</H1>
|
|
Section: Linux Programmer's Manual (3)<BR>Updated: 2019-03-06<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
glob, globfree - find pathnames matching a pattern, free memory from glob()
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<PRE>
|
|
<B>#include <<A HREF="file:///usr/include/glob.h">glob.h</A>></B>
|
|
|
|
<B>int glob(const char *</B><I>pattern</I><B>, int </B><I>flags</I><B>,</B>
|
|
<B> int (*</B><I>errfunc</I><B>) (const char *</B><I>epath</I><B>, int </B><I>eerrno</I><B>),</B>
|
|
<B> glob_t *</B><I>pglob</I><B>);</B>
|
|
<B>void globfree(glob_t *</B><I>pglob</I><B>);</B>
|
|
</PRE>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
The
|
|
<B>glob</B>()
|
|
|
|
function searches for all the pathnames matching
|
|
<I>pattern</I>
|
|
|
|
according to the rules used by the shell (see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+glob">glob</A></B>(7)).
|
|
|
|
No tilde expansion or parameter substitution is done; if you want
|
|
these, use
|
|
<B><A HREF="/cgi-bin/man/man2html?3+wordexp">wordexp</A></B>(3).
|
|
|
|
<P>
|
|
|
|
The
|
|
<B>globfree</B>()
|
|
|
|
function frees the dynamically allocated storage from an earlier call
|
|
to
|
|
<B>glob</B>().
|
|
|
|
<P>
|
|
|
|
The results of a
|
|
<B>glob</B>()
|
|
|
|
call are stored in the structure pointed to by
|
|
<I>pglob</I>.
|
|
|
|
This structure is of type
|
|
<I>glob_t</I>
|
|
|
|
(declared in
|
|
<I><<A HREF="file:///usr/include/glob.h">glob.h</A>></I>)
|
|
|
|
and includes the following elements defined by POSIX.2 (more may be
|
|
present as an extension):
|
|
<P>
|
|
|
|
|
|
|
|
typedef struct {
|
|
<BR> size_t gl_pathc; /* Count of paths matched so far */
|
|
<BR> char **gl_pathv; /* List of matched pathnames. */
|
|
<BR> size_t gl_offs; /* Slots to reserve in <I>gl_pathv</I>. */
|
|
} glob_t;
|
|
|
|
|
|
<P>
|
|
|
|
Results are stored in dynamically allocated storage.
|
|
<P>
|
|
|
|
The argument
|
|
<I>flags</I>
|
|
|
|
is made up of the bitwise OR of zero or more the following symbolic
|
|
constants, which modify the behavior of
|
|
<B>glob</B>():
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>GLOB_ERR</B>
|
|
|
|
<DD>
|
|
Return upon a read error (because a directory does not
|
|
have read permission, for example).
|
|
By default,
|
|
<B>glob</B>()
|
|
|
|
attempts carry on despite errors,
|
|
reading all of the directories that it can.
|
|
<DT id="2"><B>GLOB_MARK</B>
|
|
|
|
<DD>
|
|
Append a slash to each path which corresponds to a directory.
|
|
<DT id="3"><B>GLOB_NOSORT</B>
|
|
|
|
<DD>
|
|
Don't sort the returned pathnames.
|
|
The only reason to do this is to save processing time.
|
|
By default, the returned pathnames are sorted.
|
|
<DT id="4"><B>GLOB_DOOFFS</B>
|
|
|
|
<DD>
|
|
Reserve
|
|
<I>pglob->gl_offs</I>
|
|
|
|
slots at the beginning of the list of strings in
|
|
<I>pglob->pathv</I>.
|
|
|
|
The reserved slots contain null pointers.
|
|
<DT id="5"><B>GLOB_NOCHECK</B>
|
|
|
|
<DD>
|
|
If no pattern matches, return the original pattern.
|
|
By default,
|
|
<B>glob</B>()
|
|
|
|
returns
|
|
<B>GLOB_NOMATCH</B>
|
|
|
|
if there are no matches.
|
|
<DT id="6"><B>GLOB_APPEND</B>
|
|
|
|
<DD>
|
|
Append the results of this call to the vector of results
|
|
returned by a previous call to
|
|
<B>glob</B>().
|
|
|
|
Do not set this flag on the first invocation of
|
|
<B>glob</B>().
|
|
|
|
<DT id="7"><B>GLOB_NOESCAPE</B>
|
|
|
|
<DD>
|
|
Don't allow backslash ('\') to be used as an escape
|
|
character.
|
|
Normally, a backslash can be used to quote the following character,
|
|
providing a mechanism to turn off the special meaning
|
|
metacharacters.
|
|
</DL>
|
|
<P>
|
|
|
|
<I>flags</I>
|
|
|
|
may also include any of the following, which are GNU
|
|
extensions and not defined by POSIX.2:
|
|
<DL COMPACT>
|
|
<DT id="8"><B>GLOB_PERIOD</B>
|
|
|
|
<DD>
|
|
Allow a leading period to be matched by metacharacters.
|
|
By default, metacharacters can't match a leading period.
|
|
<DT id="9"><B>GLOB_ALTDIRFUNC</B>
|
|
|
|
<DD>
|
|
Use alternative functions
|
|
<I>pglob->gl_closedir</I>,
|
|
|
|
<I>pglob->gl_readdir</I>,
|
|
|
|
<I>pglob->gl_opendir</I>,
|
|
|
|
<I>pglob->gl_lstat</I>, and
|
|
|
|
<I>pglob->gl_stat</I>
|
|
|
|
for filesystem access instead of the normal library
|
|
functions.
|
|
<DT id="10"><B>GLOB_BRACE</B>
|
|
|
|
<DD>
|
|
Expand
|
|
<B><A HREF="/cgi-bin/man/man2html?1+csh">csh</A></B>(1)
|
|
|
|
style brace expressions of the form
|
|
<B>{a,b}</B>.
|
|
|
|
Brace expressions can be nested.
|
|
Thus, for example, specifying the pattern
|
|
"{foo/{,cat,dog},bar}" would return the same results as four separate
|
|
<B>glob</B>()
|
|
|
|
calls using the strings:
|
|
"foo/",
|
|
"foo/cat",
|
|
"foo/dog",
|
|
and
|
|
"bar".
|
|
<DT id="11"><B>GLOB_NOMAGIC</B>
|
|
|
|
<DD>
|
|
If the pattern contains no metacharacters,
|
|
then it should be returned as the sole matching word,
|
|
even if there is no file with that name.
|
|
<DT id="12"><B>GLOB_TILDE</B>
|
|
|
|
<DD>
|
|
Carry out tilde expansion.
|
|
If a tilde ('~') is the only character in the pattern,
|
|
or an initial tilde is followed immediately by a slash ('/'),
|
|
then the home directory of the caller is substituted for
|
|
the tilde.
|
|
If an initial tilde is followed by a username (e.g., "~andrea/bin"),
|
|
then the tilde and username are substituted by the home directory
|
|
of that user.
|
|
If the username is invalid, or the home directory cannot be
|
|
determined, then no substitution is performed.
|
|
<DT id="13"><B>GLOB_TILDE_CHECK</B>
|
|
|
|
<DD>
|
|
This provides behavior similar to that of
|
|
<B>GLOB_TILDE</B>.
|
|
|
|
The difference is that if the username is invalid, or the
|
|
home directory cannot be determined, then
|
|
instead of using the pattern itself as the name,
|
|
<B>glob</B>()
|
|
|
|
returns
|
|
<B>GLOB_NOMATCH</B>
|
|
|
|
to indicate an error.
|
|
<DT id="14"><B>GLOB_ONLYDIR</B>
|
|
|
|
<DD>
|
|
This is a
|
|
<I>hint</I>
|
|
|
|
to
|
|
<B>glob</B>()
|
|
|
|
that the caller is interested only in directories that match the pattern.
|
|
If the implementation can easily determine file-type information,
|
|
then nondirectory files are not returned to the caller.
|
|
However, the caller must still check that returned files
|
|
are directories.
|
|
(The purpose of this flag is merely to optimize performance when
|
|
the caller is interested only in directories.)
|
|
</DL>
|
|
<P>
|
|
|
|
If
|
|
<I>errfunc</I>
|
|
|
|
is not NULL,
|
|
it will be called in case of an error with the arguments
|
|
<I>epath</I>,
|
|
|
|
a pointer to the path which failed, and
|
|
<I>eerrno</I>,
|
|
|
|
the value of
|
|
<I>errno</I>
|
|
|
|
as returned from one of the calls to
|
|
<B><A HREF="/cgi-bin/man/man2html?3+opendir">opendir</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+readdir">readdir</A></B>(3),
|
|
|
|
or
|
|
<B><A HREF="/cgi-bin/man/man2html?2+stat">stat</A></B>(2).
|
|
|
|
If
|
|
<I>errfunc</I>
|
|
|
|
returns nonzero, or if
|
|
<B>GLOB_ERR</B>
|
|
|
|
is set,
|
|
<B>glob</B>()
|
|
|
|
will terminate after the call to
|
|
<I>errfunc</I>.
|
|
|
|
<P>
|
|
|
|
Upon successful return,
|
|
<I>pglob->gl_pathc</I>
|
|
|
|
contains the number of matched pathnames and
|
|
<I>pglob->gl_pathv</I>
|
|
|
|
contains a pointer to the list of pointers to matched pathnames.
|
|
The list of pointers is terminated by a null pointer.
|
|
<P>
|
|
|
|
It is possible to call
|
|
<B>glob</B>()
|
|
|
|
several times.
|
|
In that case, the
|
|
<B>GLOB_APPEND</B>
|
|
|
|
flag has to be set in
|
|
<I>flags</I>
|
|
|
|
on the second and later invocations.
|
|
<P>
|
|
|
|
As a GNU extension,
|
|
<I>pglob->gl_flags</I>
|
|
|
|
is set to the flags specified,
|
|
<B>or</B>ed
|
|
|
|
with
|
|
<B>GLOB_MAGCHAR</B>
|
|
|
|
if any metacharacters were found.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
On successful completion,
|
|
<B>glob</B>()
|
|
|
|
returns zero.
|
|
Other possible returns are:
|
|
<DL COMPACT>
|
|
<DT id="15"><B>GLOB_NOSPACE</B>
|
|
|
|
<DD>
|
|
for running out of memory,
|
|
<DT id="16"><B>GLOB_ABORTED</B>
|
|
|
|
<DD>
|
|
for a read error, and
|
|
<DT id="17"><B>GLOB_NOMATCH</B>
|
|
|
|
<DD>
|
|
for no found matches.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>ATTRIBUTES</H2>
|
|
|
|
For an explanation of the terms used in this section, see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+attributes">attributes</A></B>(7).
|
|
|
|
<TABLE BORDER>
|
|
<TR VALIGN=top><TD><B>Interface</B></TD><TD><B>Attribute</B></TD><TD><B>Value</B><BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>glob</B>()
|
|
|
|
</TD><TD>Thread safety</TD><TD>
|
|
MT-Unsafe race:utent env
|
|
<BR>
|
|
|
|
sig:ALRM timer locale
|
|
<BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>globfree</B>()
|
|
|
|
</TD><TD>Thread safety</TD><TD>MT-Safe<BR></TD></TR>
|
|
</TABLE>
|
|
|
|
<P>
|
|
In the above table,
|
|
<I>utent</I>
|
|
|
|
in
|
|
<I>race:utent</I>
|
|
|
|
signifies that if any of the functions
|
|
<B><A HREF="/cgi-bin/man/man2html?3+setutent">setutent</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+getutent">getutent</A></B>(3),
|
|
|
|
or
|
|
<B><A HREF="/cgi-bin/man/man2html?3+endutent">endutent</A></B>(3)
|
|
|
|
are used in parallel in different threads of a program,
|
|
then data races could occur.
|
|
<B>glob</B>()
|
|
|
|
calls those functions,
|
|
so we use race:utent to remind users.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
POSIX.1-2001, POSIX.1-2008, POSIX.2.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
The structure elements
|
|
<I>gl_pathc</I>
|
|
|
|
and
|
|
<I>gl_offs</I>
|
|
|
|
are declared as
|
|
<I>size_t</I>
|
|
|
|
in glibc 2.1, as they should be according to POSIX.2,
|
|
but are declared as
|
|
<I>int</I>
|
|
|
|
in glibc 2.0.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
The
|
|
<B>glob</B>()
|
|
|
|
function may fail due to failure of underlying function calls, such as
|
|
<B><A HREF="/cgi-bin/man/man2html?3+malloc">malloc</A></B>(3)
|
|
|
|
or
|
|
<B><A HREF="/cgi-bin/man/man2html?3+opendir">opendir</A></B>(3).
|
|
|
|
These will store their error code in
|
|
<I>errno</I>.
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>EXAMPLE</H2>
|
|
|
|
One example of use is the following code, which simulates typing
|
|
<P>
|
|
|
|
|
|
|
|
ls -l *.c ../*.c
|
|
|
|
|
|
<P>
|
|
|
|
in the shell:
|
|
<P>
|
|
|
|
|
|
|
|
glob_t globbuf;
|
|
<P>
|
|
globbuf.gl_offs = 2;
|
|
glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
|
|
glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf);
|
|
globbuf.gl_pathv[0] = "ls";
|
|
globbuf.gl_pathv[1] = "-l";
|
|
execvp("ls", &globbuf.gl_pathv[0]);
|
|
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ls">ls</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+sh">sh</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+stat">stat</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+exec">exec</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+fnmatch">fnmatch</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+malloc">malloc</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+opendir">opendir</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+readdir">readdir</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+wordexp">wordexp</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+glob">glob</A></B>(7)
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="18"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="19"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="20"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="21"><A HREF="#lbAE">RETURN VALUE</A><DD>
|
|
<DT id="22"><A HREF="#lbAF">ATTRIBUTES</A><DD>
|
|
<DT id="23"><A HREF="#lbAG">CONFORMING TO</A><DD>
|
|
<DT id="24"><A HREF="#lbAH">NOTES</A><DD>
|
|
<DT id="25"><A HREF="#lbAI">BUGS</A><DD>
|
|
<DT id="26"><A HREF="#lbAJ">EXAMPLE</A><DD>
|
|
<DT id="27"><A HREF="#lbAK">SEE ALSO</A><DD>
|
|
<DT id="28"><A HREF="#lbAL">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:45 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|