wordfree.html

IEEE 1003.1-2003, Single Unix Specification v3

fail, and the number of expanded words shall be 0.</p>

<p>Unless WRDE_SHOWERR is set in <i>flags</i>, <i>wordexp</i>() shall redirect <i>stderr</i> to <b>/dev/null</b> for any utilities
executed as a result of command substitution while expanding <i>words</i>. If WRDE_SHOWERR is set, <i>wordexp</i>() may write
messages to <i>stderr</i> if syntax errors are detected while expanding <i>words</i>.</p>

<p>The application shall ensure that if WRDE_DOOFFS is set, then <i>pwordexp</i>-&gt;<i>we_offs</i> has the same value for each
<i>wordexp</i>() call and <i>wordfree</i>() call using a given <i>pwordexp</i>.</p>

<p>The following constants are defined as error return values:</p>

<dl compact>
<dt>WRDE_BADCHAR</dt>

<dd>One of the unquoted characters- &lt;newline&gt;, <tt>'|'</tt> , <tt>'&amp;'</tt> , <tt>';'</tt> , <tt>'&lt;'</tt> ,
<tt>'&gt;'</tt> , <tt>'('</tt> , <tt>')'</tt> , <tt>'{'</tt> , <tt>'}'</tt> - appears in <i>words</i> in an inappropriate
context.</dd>

<dt>WRDE_BADVAL</dt>

<dd>Reference to undefined shell variable when WRDE_UNDEF is set in <i>flags</i>.</dd>

<dt>WRDE_CMDSUB</dt>

<dd>Command substitution requested when WRDE_NOCMD was set in <i>flags</i>.</dd>

<dt>WRDE_NOSPACE</dt>

<dd>Attempt to allocate memory failed.</dd>

<dt>WRDE_SYNTAX</dt>

<dd>Shell syntax error, such as unbalanced parentheses or unterminated string.</dd>
</dl>
</blockquote>

<h4><a name="tag_03_864_04"></a>RETURN VALUE</h4>

<blockquote>
<p>Upon successful completion, <i>wordexp</i>() shall return 0. Otherwise, a non-zero value, as described in <a href=
"../basedefs/wordexp.h.html"><i>&lt;wordexp.h&gt;</i></a>, shall be returned to indicate an error. If <i>wordexp</i>() returns the
value WRDE_NOSPACE, then <i>pwordexp</i>-&gt;<i>we_wordc</i> and <i>pwordexp</i>-&gt;<i>we_wordv</i> shall be updated to reflect
any words that were successfully expanded. In other cases, they shall not be modified.</p>

<p>The <i>wordfree</i>() function shall not return a value.</p>
</blockquote>

<h4><a name="tag_03_864_05"></a>ERRORS</h4>

<blockquote>
<p>No errors are defined.</p>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_03_864_06"></a>EXAMPLES</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_864_07"></a>APPLICATION USAGE</h4>

<blockquote>
<p>The <i>wordexp</i>() function is intended to be used by an application that wants to do all 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 of filenames) and then uses
<i>wordexp</i>() to process the input, the user could respond with anything that would be valid as input to the shell.</p>

<p>The WRDE_NOCMD flag is provided for applications that, for security or other reasons, want to prevent a user from executing
shell commands. Disallowing unquoted shell special characters also prevents unwanted side effects, such as executing a command or
writing a file.</p>
</blockquote>

<h4><a name="tag_03_864_08"></a>RATIONALE</h4>

<blockquote>
<p>This function was included as an alternative to <a href="../functions/glob.html"><i>glob</i>()</a>. There had been continuing
controversy over exactly what features should be included in <a href="../functions/glob.html"><i>glob</i>()</a>. It is hoped that
by providing <i>wordexp</i>() (which provides all of the shell word expansions, but which may be slow to execute) and <a href=
"../functions/glob.html"><i>glob</i>()</a> (which is faster, but which only performs pathname expansion, without tilde or parameter
expansion) this will satisfy the majority of applications.</p>

<p>While <i>wordexp</i>() could be implemented entirely as a library routine, it is expected that most implementations run a shell
in a subprocess to do the expansion.</p>

<p>Two different approaches have been proposed for how the required information might be presented to the shell and the results
returned. They are presented here as examples.</p>

<p>One proposal is to extend the <a href="../utilities/echo.html"><i>echo</i></a> utility by adding a <b>-q</b> option. This option
would cause <a href="../utilities/echo.html"><i>echo</i></a> to add a backslash before each backslash and &lt;blank&gt; that occurs
within an argument. The <i>wordexp</i>() function could then invoke the shell as follows:</p>

<pre>
<tt>(void) strcpy(buffer, "echo -q");
(void) strcat(buffer,</tt> <i>words</i><tt>);
if ((flags &amp; WRDE_SHOWERR) == 0)
    (void) strcat(buffer, "2&gt;/dev/null");
f = popen(buffer, "r");
</tt>
</pre>

<p>The <i>wordexp</i>() function would read the resulting output, remove unquoted backslashes, and break into words at unquoted
&lt;blank&gt;s. If the WRDE_NOCMD flag was set, <i>wordexp</i>() would have to scan <i>words</i> before starting the subshell to
make sure that there would be no command substitution. In any case, it would have to scan <i>words</i> for unquoted special
characters.</p>

<p>Another proposal is to add the following options to <a href="../utilities/sh.html"><i>sh</i></a>:</p>

<dl compact>
<dt><b>-w</b>&nbsp;<i>wordlist</i></dt>

<dd><br>
This option provides a wordlist expansion service to applications. The words in <i>wordlist</i> shall be expanded and the following
written to standard output: 

<ol>
<li>
<p>The count of the number of words after expansion, in decimal, followed by a null byte</p>
</li>

<li>
<p>The number of bytes needed to represent the expanded words (not including null separators), in decimal, followed by a null
byte</p>
</li>

<li>
<p>The expanded words, each terminated by a null byte</p>
</li>
</ol>

<p>If an error is encountered during word expansion, <a href="../utilities/sh.html"><i>sh</i></a> exits with a non-zero status
after writing the former to report any words successfully expanded</p>
</dd>

<dt><b>-P</b></dt>

<dd>Run in &quot;protected&quot; mode. If specified with the <b>-w</b> option, no command substitution shall be performed.</dd>
</dl>

<p>With these options, <i>wordexp</i>() could be implemented fairly simply by creating a subprocess using <a href=
"../functions/fork.html"><i>fork</i>()</a> and executing <a href="../utilities/sh.html"><i>sh</i></a> using the line:</p>

<pre>
<tt>execl(&lt;</tt><i>shell path</i><tt>&gt;, "sh", "-P", "-w",</tt> <i>words</i><tt>, (char *)0);
</tt>
</pre>

<p>after directing standard error to <b>/dev/null</b>.</p>

<p>It seemed objectionable for a library routine to write messages to standard error, unless explicitly requested, so
<i>wordexp</i>() is required to redirect standard error to <b>/dev/null</b> to ensure that no messages are generated, even for
commands executed for command substitution. The WRDE_SHOWERR flag can be specified to request that error messages be written.</p>

<p>The WRDE_REUSE flag allows the implementation to avoid the expense of freeing and reallocating memory, if that is possible. A
minimal implementation can call <i>wordfree</i>() when WRDE_REUSE is set.</p>
</blockquote>

<h4><a name="tag_03_864_09"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_864_10"></a>SEE ALSO</h4>

<blockquote>
<p><a href="fnmatch.html"><i>fnmatch</i>()</a> , <a href="glob.html"><i>glob</i>()</a> , the Base Definitions volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/wordexp.h.html"><i>&lt;wordexp.h&gt;</i></a>, the Shell and Utilities volume
of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../utilities/xcu_chap02.html">Chapter 2, Shell Command Language</a></p>
</blockquote>

<h4><a name="tag_03_864_11"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 4. Derived from the ISO&nbsp;POSIX-2 standard.</p>
</blockquote>

<h4><a name="tag_03_864_12"></a>Issue 5</h4>

<blockquote>
<p>Moved from POSIX2 C-language Binding to BASE.</p>
</blockquote>

<h4><a name="tag_03_864_13"></a>Issue 6</h4>

<blockquote>
<p>The DESCRIPTION is updated to avoid use of the term &quot;must&quot; for application requirements.</p>

<p>The <b>restrict</b> keyword is added to the <i>wordexp</i>() prototype for alignment with the ISO/IEC&nbsp;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 &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; 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>