📄 globfree.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html><head><!-- Copyright 1997 The Open Group, All Rights Reserved --><title>glob</title></head><body bgcolor=white><center><font size=2>The Single UNIX ® Specification, Version 2<br>Copyright © 1997 The Open Group</font></center><hr size=2 noshade><h4><a name = "tag_000_005_848"> </a>NAME</h4><blockquote>glob, globfree - generate pathnames matching a pattern</blockquote><h4><a name = "tag_000_005_849"> </a>SYNOPSIS</h4><blockquote><pre><code>#include <<a href="glob.h.html">glob.h</a>>int glob(const char *<i>pattern</i>, int <i>flags</i>, int(*<i>errfunc</i>)(const char *<i>epath</i>, int <i>errno</i>), glob_t *<i>pglob</i>);void globfree(glob_t *<i>pglob</i>);</code></pre></blockquote><h4><a name = "tag_000_005_850"> </a>DESCRIPTION</h4><blockquote>The<i>glob()</i>function is a pathname generator that implements the rulesdefined in the <b>XCU</b> specification, <b>Section 2.13</b>, <b>Pattern Matching Notation</b>,with optional support for rule 3 in the <b>XCU</b> specification, <b>Section 2.13.3</b>, <b>Patterns Used for Filename Expansion</b>.<p>The structure type<b>glob_t</b>is defined in the header<i><a href="glob.h.html"><glob.h></a></i>and includes at least the following members:<p><table bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Member Type</b><th align=center><b>Member Name</b><th align=center><b>Description</b><tr valign=top><td align=left>size_t<td align=left>gl_pathc<td align=left>Count of paths matched by <i>pattern</i>.<tr valign=top><td align=left>char **<td align=left>gl_pathv<td align=left>Pointer to a list of matched pathnames.<tr valign=top><td align=left>size_t<td align=left>gl_offs<td align=left>Slots to reserve at the beginning of <b>gl_pathv</b>.</table><p>The argument<i>pattern</i>is a pointer to a pathname pattern to be expanded. The<i>glob()</i>function matches all accessible pathnames against this pattern anddevelops 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 directoryof any filename component of<i>pattern</i>that contains any of the following special characters:<pre><code>* ? [</code></pre><p>The<i>glob()</i>function stores the number of matched pathnames into<i>pglob->gl_pathc</i>and a pointer to a list of pointers to pathnames into<i>pglob->gl_pathv</i>.The pathnames are in sort order as defined bythe current setting of the LC_COLLATE category, seethe <b>XBD</b> specification, <a href="../xbd/locale.html#tag_005_003_002"><b>LC_COLLATE</b> </a> .The first pointer after the last pathname is a null pointer.If the pattern does not match any pathnames, the returnednumber of matched paths is set to 0, and the contents of<i>pglob->gl_pathv</i>are implementation-dependent.<p>It is the caller's responsibility to create the structure pointed to by<i>pglob</i>.The<i>glob()</i>function allocates other space as needed, including the memory pointed to by<i>gl_pathv</i>.The<i>globfree()</i>function frees any space associated with<i>pglob</i>from a previous call to<i>glob()</i>.<p>The<i>flags</i>argument is used to control the behaviour of<i>glob()</i>.The value of<i>flags</i>is a bitwise inclusive OR of zero or more of the followingconstants, which are defined in the header<i><a href="glob.h.html"><glob.h></a></i>:<dl compact><dt>GLOB_APPEND<dd>Append pathnames generated to the ones from a previous call to<i>glob()</i>.<dt>GLOB_DOOFFS<dd>Make use of<i>pglob->gl_offs</i>.If this flag is set,<i>pglob->gl_offs</i>is used to specify how many nullpointers to add to the beginning of<i>pglob->gl_pathv</i>.In other words,<i>pglob->gl_pathv</i>will point tonull pointers, followed bypathname pointers, followed by a null pointer.<dt>GLOB_ERR<dd>Causes<i>glob()</i>to return when it encounters a directory that it cannot open or read.Ordinarily,<i>glob()</i>continues to find matches.<dt>GLOB_MARK<dd>Each pathname that is a directory that matches<i>pattern</i>has a slash appended.<dt>GLOB_NOCHECK<dd>Support rule 3 in the <b>XCU</b> specification, <b>Section 2.13.3</b>, <b>Patterns Used for Filename Expansion</b>.If<i>pattern</i>does not match any pathname, then<i>glob()</i>returns a list consisting of only<i>pattern</i>,and the number of matched pathnames is 1.<dt>GLOB_NOESCAPE<dd>Disable backslash escaping.<dt>GLOB_NOSORT<dd>Ordinarily,<i>glob()</i>sorts the matching pathnames according to thecurrent setting of the LC_COLLATE category, seethe <b>XBD</b> specification, <a href="../xbd/locale.html#tag_005_003_002"><b>LC_COLLATE</b> </a> .When this flag is used the order ofpathnames returned is unspecified.</dl><p>The GLOB_APPENDflag can be used to append a new set of pathnames to those found in aprevious call to<i>glob()</i>.The following rules apply 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>:<ol><p><li>The first such call must not set GLOB_APPEND.All subsequent calls must set it.<p><li>All the calls must set GLOB_DOOFFS, or all must not set it.<p><li>After the second call,<i>pglob->gl_pathv</i>points to a list containing the following:<ol type = a><p><li>Zero or more null pointers, as specified by GLOB_DOOFFS and<i>pglob->gl_offs</i><p><li>Pointers to the pathnames that were in the<i>pglob->gl_pathv</i>list before the call, in the same order as before.<p><li>Pointers to the new pathnames generated by the second call, in thespecified order.<p></ol><p><li>The count returned in<i>pglob->gl_pathc</i>will be the total number of pathnames from the two calls.<p><li>The application can change any of the fields after a call to<i>glob()</i>.If it does, it must reset them to the original value before a subsequentcall, using the same<i>pglob</i>value, to<i>globfree()</i>or<i>glob()</i>with the GLOB_APPEND flag.<p></ol><p>If, during the search, a directory is encountered thatcannot be opened or read and<i>errfunc</i>is not a null pointer,<i>glob()</i>calls(<i>*errfunc</i>())with two arguments:<ol><p><li>The<i>epath</i>argument is a pointer to the path that failed.<p><li>The<i>errno</i>argument is the value of<i>errno</i>from the failure, as set by<i><a href="opendir.html">opendir()</a></i>,<i><a href="readdir.html">readdir()</a></i>or<i><a href="stat.html">stat()</a></i>.(Other values may be used to report other errors not explicitlydocumented for those functions.)<p></ol><p>The following constants are defined as error return values for<i>glob()</i>:<dl compact><dt>GLOB_ABORTED<dd>The scan was stopped because GLOB_ERR was set or(<i>*errfunc</i>())returned non-zero.<dt>GLOB_NOMATCH<dd>The pattern does not match any existing pathname, and GLOB_NOCHECK was notset in flags.<dt>GLOB_NOSPACE<dd>An attempt to allocate memory failed.</dl><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>stops the scan and returns 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 is ignored.</blockquote><h4><a name = "tag_000_005_851"> </a>RETURN VALUE</h4><blockquote>On successful completion,<i>glob()</i>returns 0.The argument<i>pglob->gl_pathc</i>returns the number of matched pathnames and the argument<i>pglob->gl_pathv</i>contains a pointer to a null-terminated list of matchedand sorted pathnames.However, if<i>pglob->gl_pathc</i>is 0, the content of<i>pglob->gl_pathv</i>is undefined.<p>The<i>globfree()</i>function returns no value.<p>If<i>glob()</i>terminates due to an error, it returns one of thenon-zero constantsdefined in<i><a href="glob.h.html"><glob.h></a></i>.The arguments<i>pglob->gl_pathc</i>and<i>pglob->gl_pathv</i>are still set as defined above.</blockquote><h4><a name = "tag_000_005_852"> </a>ERRORS</h4><blockquote>No errors are defined.</blockquote><h4><a name = "tag_000_005_853"> </a>EXAMPLES</h4><blockquote>One use of the GLOB_DOOFFS flag is by applications thatbuild an argument list for use with<i><a href="exec.html">execv()</a></i>,<i><a href="exec.html">execve()</a></i>or<i><a href="exec.html">execvp()</a></i>.Suppose, for example, that an application wants to do the equivalent of:<pre><code>ls -l *.c</code></pre>but for some reason:<pre><code>system("ls -l *.c")</code></pre>is not acceptable.The application could obtain approximately the same result using the sequence:<pre><code>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]);</code></pre><p>Using the same example:<pre><code>ls -l *.c *.h</code></pre>could be approximately simulated using GLOB_APPEND as follows:<pre><code>globbuf.gl_offs = 2;glob ("*.c", GLOB_DOOFFS, NULL, &globbuf);glob ("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf); ...</code></pre></blockquote><h4><a name = "tag_000_005_854"> </a>APPLICATION USAGE</h4><blockquote>This function is not provided for the purpose of enabling utilities to performpathname expansion on their arguments, as this operation is performed by theshell, and utilities are explicitly not expected to redo this. Instead, it isprovided for applications that need to do pathname expansion on stringsobtained from other sources, such as a pattern typed by a user or read from afile.<p>If a utility needs to see if a pathname matches a given pattern, it can use<i><a href="fnmatch.html">fnmatch()</a></i>.<p>Note that<b>gl_pathc</b>and<b>gl_pathv</b>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<b>gl_pathc</b>is 0,<b>gl_pathv</b>is unspecified even if<i>glob()</i>did not return an error.<p>The GLOB_NOCHECK option could be used when an application wants to expanda pathname if wildcards are specified,but wants to treat the pattern as just a string otherwise.The<i><a href="../xcu/sh.html">sh</a></i>utility might use this for option-arguments, for example.<p>The new pathnames generated by a subsequent call with GLOB_APPENDare not sorted together with the previous pathnames.This mirrorsthe way that the shell handles pathname expansion when multipleexpansions are done on a command line.<p>Applications that need tilde and parameter expansion should use<i><a href="wordexp.html">wordexp()</a></i>.</blockquote><h4><a name = "tag_000_005_855"> </a>FUTURE DIRECTIONS</h4><blockquote>None.</blockquote><h4><a name = "tag_000_005_856"> </a>SEE ALSO</h4><blockquote><i><a href="exec.html">execv()</a></i>,<i><a href="fnmatch.html">fnmatch()</a></i>,<i><a href="opendir.html">opendir()</a></i>,<i><a href="readdir.html">readdir()</a></i>,<i><a href="stat.html">stat()</a></i>,<i><a href="wordexp.html">wordexp()</a></i>,<i><a href="glob.h.html"><glob.h></a></i>,the <b>XCU</b> specification.</blockquote><h4>DERIVATION</h4><blockquote>Derived from the ISO POSIX-2 standard.</blockquote><hr size=2 noshade><center><font size=2>UNIX ® is a registered Trademark of The Open Group.<br>Copyright © 1997 The Open Group<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]</font></center><hr size=2 noshade></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -