414 lines
16 KiB
HTML
414 lines
16 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>glob</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
|
|
<basefont size="3"> <a name="glob"></a> <a name="tag_03_260"></a><!-- glob -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_260_01"></a>NAME</h4>
|
|
|
|
<blockquote>glob, globfree - generate pathnames matching a pattern</blockquote>
|
|
|
|
<h4><a name="tag_03_260_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>#include <<a href="../basedefs/glob.h.html">glob.h</a>><br>
|
|
<br>
|
|
int glob(const char *restrict</tt> <i>pattern</i><tt>, int</tt> <i>flags</i><tt>,<br>
|
|
int(*</tt><i>errfunc</i><tt>)(const char *</tt><i>epath</i><tt>, int</tt>
|
|
<i>eerrno</i><tt>),<br>
|
|
glob_t *restrict</tt> <i>pglob</i><tt>);<br>
|
|
void globfree(glob_t *</tt><i>pglob</i><tt>);<br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_260_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>glob</i>() function is a pathname generator that shall implement the rules defined in the Shell and Utilities volume of
|
|
IEEE Std 1003.1-2001, <a href="../utilities/xcu_chap02.html#tag_02_13">Section 2.13, Pattern Matching Notation</a>, with
|
|
optional support for rule 3 in the Shell and Utilities volume of IEEE Std 1003.1-2001, <a href=
|
|
"../utilities/xcu_chap02.html#tag_02_13_02">Section 2.13.3, Patterns Used for Filename Expansion</a>.</p>
|
|
|
|
<p>The structure type <b>glob_t</b> is defined in <a href="../basedefs/glob.h.html"><i><glob.h></i></a> and includes at least
|
|
the following members:</p>
|
|
|
|
<center>
|
|
<table border="1" cellpadding="3" align="center">
|
|
<tr valign="top">
|
|
<th align="center">
|
|
<p class="tent"><b>Member Type</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Member Name</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Description</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><b>size_t</b></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"><i>gl_pathc</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Count of paths matched by <i>pattern</i>.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><b>char **</b></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"><i>gl_pathv</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Pointer to a list of matched pathnames.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><b>size_t</b></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"><i>gl_offs</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Slots to reserve at the beginning of <i>gl_pathv</i>.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<p>The argument <i>pattern</i> is a pointer to a pathname pattern to be expanded. The <i>glob</i>() function shall match all
|
|
accessible pathnames against this pattern and develop a list of all pathnames that match. In order to have access to a pathname,
|
|
<i>glob</i>() 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</i> that contains any of the following special characters: <tt>'*'</tt> , <tt>'?'</tt> , and
|
|
<tt>'['</tt> .</p>
|
|
|
|
<p>The <i>glob</i>() function shall store the number of matched pathnames into <i>pglob</i>-><i>gl_pathc</i> and a pointer to a
|
|
list of pointers to pathnames into <i>pglob</i>-><i>gl_pathv</i>. The pathnames shall be in sort order as defined by the current
|
|
setting of the <i>LC_COLLATE</i> category; see the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/xbd_chap07.html#tag_07_03_02">Section 7.3.2, LC_COLLATE</a>. The first pointer after the last pathname shall be a null
|
|
pointer. If the pattern does not match any pathnames, the returned number of matched paths is set to 0, and the contents of
|
|
<i>pglob</i>-><i>gl_pathv</i> are implementation-defined.</p>
|
|
|
|
<p>It is the caller's responsibility to create the structure pointed to by <i>pglob</i>. The <i>glob</i>() function shall allocate
|
|
other space as needed, including the memory pointed to by <i>gl_pathv</i>. The <i>globfree</i>() function shall free any space
|
|
associated with <i>pglob</i> from a previous call to <i>glob</i>().</p>
|
|
|
|
<p>The <i>flags</i> argument is used to control the behavior of <i>glob</i>(). The value of <i>flags</i> is a bitwise-inclusive OR
|
|
of zero or more of the following constants, which are defined in <a href="../basedefs/glob.h.html"><i><glob.h></i></a>:</p>
|
|
|
|
<dl compact>
|
|
<dt>GLOB_APPEND</dt>
|
|
|
|
<dd>Append pathnames generated to the ones from a previous call to <i>glob</i>().</dd>
|
|
|
|
<dt>GLOB_DOOFFS</dt>
|
|
|
|
<dd>Make use of <i>pglob</i>-><i>gl_offs</i>. If this flag is set, <i>pglob</i>-><i>gl_offs</i> is used to specify how many
|
|
null pointers to add to the beginning of <i>pglob</i>-><i>gl_pathv</i>. In other words, <i>pglob</i>-><i>gl_pathv</i> shall
|
|
point to <i>pglob</i>-><i>gl_offs</i> null pointers, followed by <i>pglob</i>-><i>gl_pathc</i> pathname pointers, followed by
|
|
a null pointer.</dd>
|
|
|
|
<dt>GLOB_ERR</dt>
|
|
|
|
<dd>Cause <i>glob</i>() to return when it encounters a directory that it cannot open or read. Ordinarily, <i>glob</i>() continues
|
|
to find matches.</dd>
|
|
|
|
<dt>GLOB_MARK</dt>
|
|
|
|
<dd>Each pathname that is a directory that matches <i>pattern</i> shall have a slash appended.</dd>
|
|
|
|
<dt>GLOB_NOCHECK</dt>
|
|
|
|
<dd>Supports rule 3 in the Shell and Utilities volume of IEEE Std 1003.1-2001, <a href=
|
|
"../utilities/xcu_chap02.html#tag_02_13_02">Section 2.13.3, Patterns Used for Filename Expansion</a>. If <i>pattern</i> does not
|
|
match any pathname, then <i>glob</i>() shall return a list consisting of only <i>pattern</i>, and the number of matched pathnames
|
|
is 1.</dd>
|
|
|
|
<dt>GLOB_NOESCAPE</dt>
|
|
|
|
<dd>Disable backslash escaping.</dd>
|
|
|
|
<dt>GLOB_NOSORT</dt>
|
|
|
|
<dd>Ordinarily, <i>glob</i>() sorts the matching pathnames according to the current setting of the <i>LC_COLLATE</i> category; see
|
|
the Base Definitions volume of IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap07.html#tag_07_03_02">Section 7.3.2,
|
|
LC_COLLATE</a>. When this flag is used, the order of pathnames returned is unspecified.</dd>
|
|
</dl>
|
|
|
|
<p>The GLOB_APPEND flag can be used to append a new set of pathnames to those found in a previous call to <i>glob</i>(). The
|
|
following rules apply to applications when two or more calls to <i>glob</i>() are made with the same value of <i>pglob</i> and
|
|
without intervening calls to <i>globfree</i>():</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>The first such call shall not set GLOB_APPEND. All subsequent calls shall set it.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>All the calls shall set GLOB_DOOFFS, or all shall not set it.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>After the second call, <i>pglob</i>-><i>gl_pathv</i> points to a list containing the following:</p>
|
|
|
|
<ol type="a">
|
|
<li>
|
|
<p>Zero or more null pointers, as specified by GLOB_DOOFFS and <i>pglob</i>-><i>gl_offs</i>.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Pointers to the pathnames that were in the <i>pglob</i>-><i>gl_pathv</i> list before the call, in the same order as
|
|
before.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Pointers to the new pathnames generated by the second call, in the specified order.</p>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The count returned in <i>pglob</i>-><i>gl_pathc</i> shall be the total number of pathnames from the two calls.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The application can change any of the fields after a call to <i>glob</i>(). If it does, the application shall reset them to the
|
|
original value before a subsequent call, using the same <i>pglob</i> value, to <i>globfree</i>() or <i>glob</i>() with the
|
|
GLOB_APPEND flag.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>If, during the search, a directory is encountered that cannot be opened or read and <i>errfunc</i> is not a null pointer,
|
|
<i>glob</i>() calls (<i>*errfunc</i>()) with two arguments:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>The <i>epath</i> argument is a pointer to the path that failed.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The <i>eerrno</i> argument is the value of <i>errno</i> from the failure, as set by <a href=
|
|
"../functions/opendir.html"><i>opendir</i>()</a>, <a href="../functions/readdir.html"><i>readdir</i>()</a>, or <a href=
|
|
"../functions/stat.html"><i>stat</i>()</a>. (Other values may be used to report other errors not explicitly documented for those
|
|
functions.)</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>If (<i>*errfunc</i>()) is called and returns non-zero, or if the GLOB_ERR flag is set in <i>flags</i>, <i>glob</i>() shall stop
|
|
the scan and return GLOB_ABORTED after setting <i>gl_pathc</i> and <i>gl_pathv</i> in <i>pglob</i> to reflect the paths already
|
|
scanned. If GLOB_ERR is not set and either <i>errfunc</i> is a null pointer or (<i>*errfunc</i>()) returns 0, the error shall be
|
|
ignored.</p>
|
|
|
|
<p>The <i>glob</i>() function shall not fail because of large files.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_260_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, <i>glob</i>() shall return 0. The argument <i>pglob</i>-><i>gl_pathc</i> shall return the number
|
|
of matched pathnames and the argument <i>pglob</i>-><i>gl_pathv</i> shall contain a pointer to a null-terminated list of matched
|
|
and sorted pathnames. However, if <i>pglob</i>-><i>gl_pathc</i> is 0, the content of <i>pglob</i>-><i>gl_pathv</i> is
|
|
undefined.</p>
|
|
|
|
<p>The <i>globfree</i>() function shall not return a value.</p>
|
|
|
|
<p>If <i>glob</i>() terminates due to an error, it shall return one of the non-zero constants defined in <a href=
|
|
"../basedefs/glob.h.html"><i><glob.h></i></a>. The arguments <i>pglob</i>-><i>gl_pathc</i> and
|
|
<i>pglob</i>-><i>gl_pathv</i> are still set as defined above.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_260_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>glob</i>() function shall fail and return the corresponding value if:</p>
|
|
|
|
<dl compact>
|
|
<dt>GLOB_ABORTED</dt>
|
|
|
|
<dd>The scan was stopped because GLOB_ERR was set or (<i>*errfunc</i>()) returned non-zero.</dd>
|
|
|
|
<dt>GLOB_NOMATCH</dt>
|
|
|
|
<dd>The pattern does not match any existing pathname, and GLOB_NOCHECK was not set in flags.</dd>
|
|
|
|
<dt>GLOB_NOSPACE</dt>
|
|
|
|
<dd>An attempt to allocate memory failed.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_260_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>One use of the GLOB_DOOFFS flag is by applications that build an argument list for use with <a href=
|
|
"../functions/execv.html"><i>execv</i>()</a>, <a href="../functions/execve.html"><i>execve</i>()</a>, or <a href=
|
|
"../functions/execvp.html"><i>execvp</i>()</a>. Suppose, for example, that an application wants to do the equivalent of:</p>
|
|
|
|
<pre>
|
|
<tt>ls -l *.c
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>but for some reason:</p>
|
|
|
|
<pre>
|
|
<tt>system("ls -l *.c")
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>is not acceptable. The application could obtain approximately the same result using the sequence:</p>
|
|
|
|
<pre>
|
|
<tt>globbuf.gl_offs = 2;
|
|
glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
|
|
globbuf.gl_pathv[0] = "ls";
|
|
globbuf.gl_pathv[1] = "-l";
|
|
execvp("ls", &globbuf.gl_pathv[0]);
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>Using the same example:</p>
|
|
|
|
<pre>
|
|
<tt>ls -l *.c *.h
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>could be approximately simulated using GLOB_APPEND as follows:</p>
|
|
|
|
<pre>
|
|
<tt>globbuf.gl_offs = 2;
|
|
glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
|
|
glob("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf);
|
|
...
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_260_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>This function is not provided for the purpose of enabling utilities to perform pathname expansion on their arguments, as this
|
|
operation is performed by the shell, and utilities are explicitly not expected to redo this. Instead, it is provided for
|
|
applications that need to do pathname expansion on strings obtained from other sources, such as a pattern typed by a user or read
|
|
from a file.</p>
|
|
|
|
<p>If a utility needs to see if a pathname matches a given pattern, it can use <a href=
|
|
"../functions/fnmatch.html"><i>fnmatch</i>()</a>.</p>
|
|
|
|
<p>Note that <i>gl_pathc</i> and <i>gl_pathv</i> have meaning even if <i>glob</i>() fails. This allows <i>glob</i>() to report
|
|
partial results in the event of an error. However, if <i>gl_pathc</i> is 0, <i>gl_pathv</i> is unspecified even if <i>glob</i>()
|
|
did not return an error.</p>
|
|
|
|
<p>The GLOB_NOCHECK option could be used when an application wants to expand a pathname if wildcards are specified, but wants to
|
|
treat the pattern as just a string otherwise. The <a href="../utilities/sh.html"><i>sh</i></a> utility might use this for
|
|
option-arguments, for example.</p>
|
|
|
|
<p>The new pathnames generated by a subsequent call with GLOB_APPEND are not sorted together with the previous pathnames. This
|
|
mirrors the way that the shell handles pathname expansion when multiple expansions are done on a command line.</p>
|
|
|
|
<p>Applications that need tilde and parameter expansion should use <a href="../functions/wordexp.html"><i>wordexp</i>()</a>.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_260_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>It was claimed that the GLOB_DOOFFS flag is unnecessary because it could be simulated using:</p>
|
|
|
|
<pre>
|
|
<tt>new = (char **)malloc((n + pglob->gl_pathc + 1)
|
|
* sizeof(char *));
|
|
(void) memcpy(new+n, pglob->gl_pathv,
|
|
pglob->gl_pathc * sizeof(char *));
|
|
(void) memset(new, 0, n * sizeof(char *));
|
|
free(pglob->gl_pathv);
|
|
pglob->gl_pathv = new;
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>However, this assumes that the memory pointed to by <i>gl_pathv</i> is a block that was separately created using <a href=
|
|
"../functions/malloc.html"><i>malloc</i>()</a>. This is not necessarily the case. An application should make no assumptions about
|
|
how the memory referenced by fields in <i>pglob</i> was allocated. It might have been obtained from <a href=
|
|
"../functions/malloc.html"><i>malloc</i>()</a> in a large chunk and then carved up within <i>glob</i>(), or it might have been
|
|
created using a different memory allocator. It is not the intent of the standard developers to specify or imply how the memory used
|
|
by <i>glob</i>() is managed.</p>
|
|
|
|
<p>The GLOB_APPEND flag would be used when an application wants to expand several different patterns into a single list.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_260_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_260_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="exec.html"><i><a href="../functions/exec.html">exec</a></i>()</a> , <a href="fnmatch.html"><i>fnmatch</i>()</a> , <a
|
|
href="opendir.html"><i>opendir</i>()</a> , <a href="readdir.html"><i>readdir</i>()</a> , <a href="stat.html"><i>stat</i>()</a> , <a
|
|
href="wordexp.html"><i>wordexp</i>()</a> , the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/glob.h.html"><i><glob.h></i></a>, the Shell and Utilities volume of IEEE Std 1003.1-2001</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_260_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 4. Derived from the ISO POSIX-2 standard.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_260_12"></a>Issue 5</h4>
|
|
|
|
<blockquote>
|
|
<p>Moved from POSIX2 C-language Binding to BASE.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_260_13"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The DESCRIPTION is updated to avoid use of the term "must" for application requirements.</p>
|
|
|
|
<p>The <b>restrict</b> keyword is added to the <i>glob</i>() prototype for alignment with the ISO/IEC 9899:1999 standard.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|