419 lines
18 KiB
HTML
419 lines
18 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>wordexp</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
|
|
<basefont size="3"> <a name="wordexp"></a> <a name="tag_03_864"></a><!-- wordexp -->
|
|
<!--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_864_01"></a>NAME</h4>
|
|
|
|
<blockquote>wordexp, wordfree - perform word expansions</blockquote>
|
|
|
|
<h4><a name="tag_03_864_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>#include <<a href="../basedefs/wordexp.h.html">wordexp.h</a>><br>
|
|
<br>
|
|
int wordexp(const char *restrict</tt> <i>words</i><tt>, wordexp_t *restrict</tt> <i>pwordexp</i><tt>,<br>
|
|
int</tt> <i>flags</i><tt>);<br>
|
|
void wordfree(wordexp_t *</tt><i>pwordexp</i><tt>);<br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_864_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>wordexp</i>() function shall perform word expansions as described in the Shell and Utilities volume of
|
|
IEEE Std 1003.1-2001, <a href="../utilities/xcu_chap02.html#tag_02_06">Section 2.6, Word Expansions</a>, subject to
|
|
quoting as in the Shell and Utilities volume of IEEE Std 1003.1-2001, <a href=
|
|
"../utilities/xcu_chap02.html#tag_02_02">Section 2.2, Quoting</a>, and place the list of expanded words into the structure pointed
|
|
to by <i>pwordexp</i>.</p>
|
|
|
|
<p>The <i>words</i> argument is a pointer to a string containing one or more words to be expanded. The expansions shall be the same
|
|
as would be performed by the command line interpreter if <i>words</i> were the part of a command line representing the arguments to
|
|
a utility. Therefore, the application shall ensure that <i>words</i> does not contain an unquoted <newline> or any of the
|
|
unquoted shell special characters <tt>'|'</tt> , <tt>'&'</tt> , <tt>';'</tt> , <tt>'<'</tt> , <tt>'>'</tt> except in the
|
|
context of command substitution as specified in the Shell and Utilities volume of IEEE Std 1003.1-2001, <a href=
|
|
"../utilities/xcu_chap02.html#tag_02_06_03">Section 2.6.3, Command Substitution</a>. It also shall not contain unquoted parentheses
|
|
or braces, except in the context of command or variable substitution. The application shall ensure that every member of
|
|
<i>words</i> which it expects to have expanded by <i>wordexp</i>() does not contain an unquoted initial comment character. The
|
|
application shall also ensure that any words which it intends to be ignored (because they begin or continue a comment) are deleted
|
|
from <i>words</i>. If the argument <i>words</i> contains an unquoted comment character (number sign) that is the beginning of a
|
|
token, <i>wordexp</i>() shall either treat the comment character as a regular character, or interpret it as a comment indicator and
|
|
ignore the remainder of <i>words</i>.</p>
|
|
|
|
<p>The structure type <b>wordexp_t</b> is defined in the <a href="../basedefs/wordexp.h.html"><i><wordexp.h></i></a> header
|
|
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>we_wordc</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Count of words matched by <i>words</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>we_wordv</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Pointer to list of expanded words.</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>we_offs</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Slots to reserve at the beginning of <i>pwordexp</i>-><i>we_wordv</i>.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<p>The <i>wordexp</i>() function shall store the number of generated words into <i>pwordexp</i>-><i>we_wordc</i> and a pointer
|
|
to a list of pointers to words in <i>pwordexp</i>-><i>we_wordv</i>. Each individual field created during field splitting (see
|
|
the Shell and Utilities volume of IEEE Std 1003.1-2001, <a href="../utilities/xcu_chap02.html#tag_02_06_05">Section
|
|
2.6.5, Field Splitting</a>) or pathname expansion (see the Shell and Utilities volume of IEEE Std 1003.1-2001, <a href=
|
|
"../utilities/xcu_chap02.html#tag_02_06_06">Section 2.6.6, Pathname Expansion</a>) shall be a separate word in the
|
|
<i>pwordexp</i>-><i>we_wordv</i> list. The words shall be in order as described in the Shell and Utilities volume of
|
|
IEEE Std 1003.1-2001, <a href="../utilities/xcu_chap02.html#tag_02_06">Section 2.6, Word Expansions</a>. The first
|
|
pointer after the last word pointer shall be a null pointer. The expansion of special parameters described in the Shell and
|
|
Utilities volume of IEEE Std 1003.1-2001, <a href="../utilities/xcu_chap02.html#tag_02_05_02">Section 2.5.2, Special
|
|
Parameters</a> is unspecified.</p>
|
|
|
|
<p>It is the caller's responsibility to allocate the storage pointed to by <i>pwordexp</i>. The <i>wordexp</i>() function shall
|
|
allocate other space as needed, including memory pointed to by <i>pwordexp</i>-><i>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>
|
|
|
|
<p>The <i>flags</i> argument is used to control the behavior 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 <a href=
|
|
"../basedefs/wordexp.h.html"><i><wordexp.h></i></a>:</p>
|
|
|
|
<dl compact>
|
|
<dt>WRDE_APPEND</dt>
|
|
|
|
<dd>Append words generated to the ones from a previous call to <i>wordexp</i>().</dd>
|
|
|
|
<dt>WRDE_DOOFFS</dt>
|
|
|
|
<dd>Make use of <i>pwordexp</i>-><i>we_offs</i>. If this flag is set, <i>pwordexp</i>-><i>we_offs</i> is used to specify how
|
|
many null pointers to add to the beginning of <i>pwordexp</i>-><i>we_wordv</i>. In other words,
|
|
<i>pwordexp</i>-><i>we_wordv</i> shall point to <i>pwordexp</i>-><i>we_offs</i> null pointers, followed by
|
|
<i>pwordexp</i>-><i>we_wordc</i> word pointers, followed by a null pointer.</dd>
|
|
|
|
<dt>WRDE_NOCMD</dt>
|
|
|
|
<dd>If the implementation supports the utilities defined in the Shell and Utilities volume of IEEE Std 1003.1-2001, fail
|
|
if command substitution, as specified in the Shell and Utilities volume of IEEE Std 1003.1-2001, <a href=
|
|
"../utilities/xcu_chap02.html#tag_02_06_03">Section 2.6.3, Command Substitution</a>, is requested.</dd>
|
|
|
|
<dt>WRDE_REUSE</dt>
|
|
|
|
<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 shall be the same as if the application had called <i>wordfree</i>() and then called <i>wordexp</i>()
|
|
without WRDE_REUSE.</dd>
|
|
|
|
<dt>WRDE_SHOWERR</dt>
|
|
|
|
<dd>Do not redirect <i>stderr</i> to <b>/dev/null</b>.</dd>
|
|
|
|
<dt>WRDE_UNDEF</dt>
|
|
|
|
<dd>Report error on an attempt to expand an undefined shell variable.</dd>
|
|
</dl>
|
|
|
|
<p>The WRDE_APPEND flag can be used to append a new set of words to those generated by a previous call to <i>wordexp</i>(). The
|
|
following rules apply to applications 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>():</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>The first such call shall not set WRDE_APPEND. All subsequent calls shall set it.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>All of the calls shall set WRDE_DOOFFS, or all shall not set it.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>After the second and each subsequent call, <i>pwordexp</i>-><i>we_wordv</i> shall point to a list containing the
|
|
following:</p>
|
|
|
|
<ol type="a">
|
|
<li>
|
|
<p>Zero or more null pointers, as specified by WRDE_DOOFFS and <i>pwordexp</i>-><i>we_offs</i></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Pointers to the words that were in the <i>pwordexp</i>-><i>we_wordv</i> list before the call, in the same order as before</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Pointers to the new words generated by the latest call, in the specified order</p>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The count returned in <i>pwordexp</i>-><i>we_wordc</i> shall be the total number of words from all of the calls.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The application can change any of the fields after a call to <i>wordexp</i>(), but if it does it shall reset them to the
|
|
original value before a subsequent call, using the same <i>pwordexp</i> value, to <i>wordfree</i>() or <i>wordexp</i>() with the
|
|
WRDE_APPEND or WRDE_REUSE flag.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>If the implementation supports the utilities defined in the Shell and Utilities volume of IEEE Std 1003.1-2001, and
|
|
<i>words</i> contains an unquoted character- <newline>, <tt>'|'</tt> , <tt>'&'</tt> , <tt>';'</tt> , <tt>'<'</tt> ,
|
|
<tt>'>'</tt> , <tt>'('</tt> , <tt>')'</tt> , <tt>'{'</tt> , <tt>'}'</tt> - in an inappropriate context, <i>wordexp</i>() shall
|
|
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>-><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- <newline>, <tt>'|'</tt> , <tt>'&'</tt> , <tt>';'</tt> , <tt>'<'</tt> ,
|
|
<tt>'>'</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><wordexp.h></i></a>, shall be returned to indicate an error. If <i>wordexp</i>() returns the
|
|
value WRDE_NOSPACE, then <i>pwordexp</i>-><i>we_wordc</i> and <i>pwordexp</i>-><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 <blank> 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 & WRDE_SHOWERR) == 0)
|
|
(void) strcat(buffer, "2>/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
|
|
<blank>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> <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 "protected" 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(<</tt><i>shell path</i><tt>>, "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 Std 1003.1-2001, <a href="../basedefs/wordexp.h.html"><i><wordexp.h></i></a>, the Shell and Utilities volume
|
|
of IEEE Std 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 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 "must" for application requirements.</p>
|
|
|
|
<p>The <b>restrict</b> keyword is added to the <i>wordexp</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>
|
|
|