📄 wordfree.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html><head><!-- Copyright 1997 The Open Group, All Rights Reserved --><title>wordexp</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_010_800"> </a>NAME</h4><blockquote>wordexp, wordfree - perform word expansions</blockquote><h4><a name = "tag_000_010_801"> </a>SYNOPSIS</h4><blockquote><pre><code>#include <<a href="wordexp.h.html">wordexp.h</a>>int wordexp(const char *<i>words</i>, wordexp_t *<i>pwordexp</i>, int <i>flags</i>);void wordfree(wordexp_t *<i>pwordexp</i>);</code></pre></blockquote><h4><a name = "tag_000_010_802"> </a>DESCRIPTION</h4><blockquote>The<i>wordexp()</i>function performs word expansions as described in the <b>XCU</b> specification, <a href="../xcu/chap2.html#tag_001_006"><b>Word Expansions</b> </a>,subject to quoting as in the <b>XCU</b> specification, <b>Section 2.2</b>, <b>Quoting</b>,and places the list of expanded words into the structurepointed to by<i>pwordexp</i>.<p>The<i>words</i>argument is a pointer to a string containing one or more words to be expanded.The expansions will be the same as would beperformed by the shell if<i>words</i>were the part of a command line representing the arguments to a utility.Therefore,<i>words</i>must not contain an unquoted newlineor any of the unquoted shell special characters:<pre><code>| & ; < ></code></pre>except in the context of command substitution as specified in the <b>XCU</b> specification, <a href="../xcu/chap2.html#tag_001_006_003"><b>Command Substitution</b> </a>. Italso must not contain unquoted parentheses or braces, except in the context ofcommand or variable substitution. If the argument<i>words</i>contains an unquoted comment character (number sign) that is thebeginning of a token,<i>wordexp()</i>may treat the comment character as a regularcharacter, or may interpret it as a comment indicator and ignore theremainder of<i>words</i>.<p>The structure type<b>wordexp_t</b>is defined in the header<i><a href="wordexp.h.html"><wordexp.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>we_wordc<td align=left>Count of words matched by <i>words</i>.<tr valign=top><td align=left>char **<td align=left>we_wordv<td align=left>Pointer to list of expanded words.<tr valign=top><td align=left>size_t<td align=left>we_offs<td align=left>Slots to reserve at the beginning of <i>pwordexp-></i><b>we_wordv</b>.</table><p>The<i>wordexp()</i>function stores the number of generated words into<i>pwordexp->we_wordc</i>and a pointer to a list of pointers to words in<i>pwordexp->we_wordv</i>.Each individual field created duringfield splitting (see the <b>XCU</b> specification, <a href="../xcu/chap2.html#tag_001_006_005"><b>Field Splitting</b> </a>) or pathname expansion (see the <b>XCU</b> specification, <a href="../xcu/chap2.html#tag_001_006_006"><b>Pathname Expansion</b> </a>)is a separate word in the<i>pwordexp->we_wordv</i>list.The words are in order as described in the <b>XCU</b> specification, <a href="../xcu/chap2.html#tag_001_006"><b>Word Expansions</b> </a>.The first pointer after the last word pointer will be a null pointer.The expansion of special parameters described in the <b>XCU</b> specification, <a href="../xcu/chap2.html#tag_001_005_002"><b>Special Parameters</b> </a> is unspecified.<p>It is the caller's responsibility to allocate the storagepointed to by<i>pwordexp</i>.The<i>wordexp()</i>function allocates other space as needed, including memory pointed to by<i>pwordexp->we_wordv</i>.The<i>wordfree()</i>function frees any memory associated with<i>pwordexp</i>from a previous call to<i>wordexp()</i>.<p>The<i>flags</i>argument is used to control the behaviour of<i>wordexp()</i>.The value of<i>flags</i>is the bitwise inclusive OR of zero or more of the following constants,which are defined in<i><a href="wordexp.h.html"><wordexp.h></a></i>:<dl compact><dt>WRDE_APPEND<dd>Append words generated to the ones from a previous call to<i>wordexp()</i>.<dt>WRDE_DOOFFS<dd>Make use of<i>pwordexp->we_offs</i>.If this flag is set,<i>pwordexp->we_offs</i>is used to specify how many nullpointers to add to the beginning of<i>pwordexp->we_wordv</i>.In other words,<i>pwordexp->we_wordv</i>will point to<i>pwordexp->we_offs</i>null pointers, followed by<i>pwordexp->we_wordc</i>word pointers, followed by a null pointer.<dt>WRDE_NOCMD<dd>Fail if command substitution, as specified in the <b>XCU</b> specification, <a href="../xcu/chap2.html#tag_001_006_003"><b>Command Substitution</b> </a>, is requested.<dt>WRDE_REUSE<dd>The<i>pwordexp</i>argument was passed to a previous successful call to<i>wordexp()</i>,and has not been passed to<i>wordfree()</i>.The result will be the same as if the application hadcalled<i>wordfree()</i>and then called<i>wordexp()</i>without WRDE_REUSE.<dt>WRDE_SHOWERR<dd>Do not redirect<i>stderr</i>to<b>/dev/null</b>.<dt>WRDE_UNDEF<dd>Report error on an attempt to expand an undefined shell variable.</dl><p>The WRDE_APPENDflag can be used to append a new set of words to those generated by aprevious call to<i>wordexp()</i>.The following rules apply when two or more calls to<i>wordexp()</i>are made with the same value of<i>pwordexp</i>and without intervening calls to<i>wordfree()</i>:<ol><p><li>The first such call must not set WRDE_APPEND.All subsequent calls must set it.<p><li>All of the calls must set WRDE_DOOFFS, or all must not set it.<p><li>After the second and each subsequent call,<i>pwordexp->we_wordv</i>will point to a list containing the following:<ol type = a><p><li>zero or more null pointers, as specified by WRDE_DOOFFS and<i>pwordexp->we_offs</i><p><li>pointers to the words that were in the<i>pwordexp->we_wordv</i>list before the call, in the same order as before<p><li>pointers to the new words generated by the latest call, in thespecified order<p></ol><p><li>The count returned in<i>pwordexp->we_wordc</i>will be the total number of words from all of the calls.<br><p><li>The application can change any of the fields after a call to<i>wordexp()</i>,but if it does it must reset them to the original value before a subsequentcall, using the same<i>pwordexp</i>value, to<i>wordfree()</i>or<i>wordexp()</i>with the WRDE_APPEND or WRDE_REUSE flag.<p></ol><p>If<i>words</i>contains an unquoted:<pre><code><newline> | & ; < > ( ) { }</code></pre><p>in an inappropriate context,<i>wordexp()</i>will fail, and the number of expanded words will be 0.<p>Unless WRDE_SHOWERR is set in<i>flags</i>,<i>wordexp()</i>will redirect<i>stderr</i>to<b>/dev/null</b>for any utilities executed as a result of command substitution whileexpanding<i>words</i>.If WRDE_SHOWERR is set,<i>wordexp()</i>may write messages to<i>stderr</i>if syntax errors are detectedwhile expanding<i>words</i>.<p>If WRDE_DOOFFS is set, thenmust have the same value for each<i>wordexp()</i>call and<i>wordfree()</i>call using a given<i>pwordexp</i>.<p>The following constants are defined as error return values:<dl compact><dt>WRDE_BADCHAR<dd>One of the unquoted characters:<pre><code><newline> | & ; < > ( ) { }</code></pre>appears in<i>words</i>in an inappropriate context.<dt>WRDE_BADVAL<dd>Reference to undefined shell variable when WRDE_UNDEF is set in<i>flags</i>.<dt>WRDE_CMDSUB<dd>Command substitution requested when WRDE_NOCMDwas set in flags.<dt>WRDE_NOSPACE<dd>Attempt to allocate memory failed.<dt>WRDE_SYNTAX<dd>Shell syntax error, such as unbalancedparentheses or unterminated string.</dl></blockquote><h4><a name = "tag_000_010_803"> </a>RETURN VALUE</h4><blockquote>On successful completion,<i>wordexp()</i>returns 0.<p>Otherwise, a non-zero value as described in<i><a href="wordexp.h.html"><wordexp.h></a></i>is returned to indicate an error. If<i>wordexp()</i>returns the value WRDE_NOSPACE, then<i>pwordexp->we_wordc</i>and<i>pwordexp->we_wordv</i>will be updated to reflect any wordsthat were successfully expanded.In other cases, they will not be modified.<p>The<i>wordfree()</i>function returns no value.</blockquote><h4><a name = "tag_000_010_804"> </a>ERRORS</h4><blockquote>No errors are defined.</blockquote><h4><a name = "tag_000_010_805"> </a>EXAMPLES</h4><blockquote>None.</blockquote><h4><a name = "tag_000_010_806"> </a>APPLICATION USAGE</h4><blockquote>This function is intended to be used by an application that wants to doall of the shell's expansions on a word or words obtained from a user.For example, if the application prompts for a filename (or list offilenames) and then uses<i>wordexp()</i>to process the input,the user could respond with anything that would be valid asinput to the shell.<p>The WRDE_NOCMDflag is provided for applications that, for security or other reasons,want to prevent a user from executing shell commands.Disallowing unquoted shell special charactersalso prevents unwanted side effects such as executing a command orwriting a file.</blockquote><h4><a name = "tag_000_010_807"> </a>FUTURE DIRECTIONS</h4><blockquote>None.</blockquote><h4><a name = "tag_000_010_808"> </a>SEE ALSO</h4><blockquote><i><a href="fnmatch.html">fnmatch()</a></i>,<i><a href="glob.html">glob()</a></i>,<i><a href="wordexp.h.html"><wordexp.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 + -