377 lines
8.3 KiB
HTML
377 lines
8.3 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of WORDEXP</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>WORDEXP</H1>
|
|
Section: Linux Programmer's Manual (3)<BR>Updated: 2017-09-15<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
wordexp, wordfree - perform word expansion like a posix-shell
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>#include <<A HREF="file:///usr/include/wordexp.h">wordexp.h</A>></B>
|
|
|
|
<P>
|
|
|
|
<B>int wordexp(const char *</B><I>s</I><B>, wordexp_t *</B><I>p</I><B>, int </B><I>flags</I><B>);</B>
|
|
|
|
<P>
|
|
|
|
<B>void wordfree(wordexp_t *</B><I>p</I><B>);</B>
|
|
|
|
<P>
|
|
|
|
|
|
Feature Test Macro Requirements for glibc (see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+feature_test_macros">feature_test_macros</A></B>(7)):
|
|
|
|
|
|
<P>
|
|
|
|
<B>wordexp</B>(),
|
|
|
|
<B>wordfree</B>():
|
|
|
|
_XOPEN_SOURCE
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
The function
|
|
<B>wordexp</B>()
|
|
|
|
performs a shell-like expansion of the string
|
|
<I>s</I>
|
|
|
|
and returns the result in the structure pointed to by
|
|
<I>p</I>.
|
|
|
|
The data type
|
|
<I>wordexp_t</I>
|
|
|
|
is a structure that at least has the fields
|
|
<I>we_wordc</I>,
|
|
|
|
<I>we_wordv</I>,
|
|
|
|
and
|
|
<I>we_offs</I>.
|
|
|
|
The field
|
|
<I>we_wordc</I>
|
|
|
|
is a
|
|
<I>size_t</I>
|
|
|
|
that gives the number of words in the expansion of
|
|
<I>s</I>.
|
|
|
|
The field
|
|
<I>we_wordv</I>
|
|
|
|
is a
|
|
<I>char **</I>
|
|
|
|
that points to the array of words found.
|
|
The field
|
|
<I>we_offs</I>
|
|
|
|
of type
|
|
<I>size_t</I>
|
|
|
|
is sometimes (depending on
|
|
<I>flags</I>,
|
|
|
|
see below) used to indicate the number of initial elements in the
|
|
<I>we_wordv</I>
|
|
|
|
array that should be filled with NULLs.
|
|
<P>
|
|
|
|
The function
|
|
<B>wordfree</B>()
|
|
|
|
frees the allocated memory again.
|
|
More precisely, it does not free
|
|
its argument, but it frees the array
|
|
<I>we_wordv</I>
|
|
|
|
and the strings that points to.
|
|
<A NAME="lbAE"> </A>
|
|
<H3>The string argument</H3>
|
|
|
|
Since the expansion is the same as the expansion by the shell (see
|
|
<B><A HREF="/cgi-bin/man/man2html?1+sh">sh</A></B>(1))
|
|
|
|
of the parameters to a command, the string
|
|
<I>s</I>
|
|
|
|
must not contain characters that would be illegal in shell command
|
|
parameters.
|
|
In particular, there must not be any unescaped
|
|
newline or |, &, ;, <, >, (, ), {, } characters
|
|
outside a command substitution or parameter substitution context.
|
|
<P>
|
|
|
|
If the argument
|
|
<I>s</I>
|
|
|
|
contains a word that starts with an unquoted comment character #,
|
|
then it is unspecified whether that word and all following words
|
|
are ignored, or the # is treated as a non-comment character.
|
|
<A NAME="lbAF"> </A>
|
|
<H3>The expansion</H3>
|
|
|
|
The expansion done consists of the following stages:
|
|
tilde expansion (replacing ~user by user's home directory),
|
|
variable substitution (replacing $FOO by the value of the environment
|
|
variable FOO), command substitution (replacing $(command) or `command`
|
|
by the output of command), arithmetic expansion, field splitting,
|
|
wildcard expansion, quote removal.
|
|
<P>
|
|
|
|
The result of expansion of special parameters
|
|
($@, $*, $#, $?, $-, $$, $!, $0) is unspecified.
|
|
<P>
|
|
|
|
Field splitting is done using the environment variable $IFS.
|
|
If it is not set, the field separators are space, tab and newline.
|
|
<A NAME="lbAG"> </A>
|
|
<H3>The output array</H3>
|
|
|
|
The array
|
|
<I>we_wordv</I>
|
|
|
|
contains the words found, followed by a NULL.
|
|
<A NAME="lbAH"> </A>
|
|
<H3>The flags argument</H3>
|
|
|
|
The
|
|
<I>flag</I>
|
|
|
|
argument is a bitwise inclusive OR of the following values:
|
|
<DL COMPACT>
|
|
<DT id="1"><B>WRDE_APPEND</B>
|
|
|
|
<DD>
|
|
Append the words found to the array resulting from a previous call.
|
|
<DT id="2"><B>WRDE_DOOFFS</B>
|
|
|
|
<DD>
|
|
Insert
|
|
<I>we_offs</I>
|
|
|
|
initial NULLs in the array
|
|
<I>we_wordv</I>.
|
|
|
|
(These are not counted in the returned
|
|
<I>we_wordc</I>.)
|
|
|
|
<DT id="3"><B>WRDE_NOCMD</B>
|
|
|
|
<DD>
|
|
Don't do command substitution.
|
|
<DT id="4"><B>WRDE_REUSE</B>
|
|
|
|
<DD>
|
|
The argument
|
|
<I>p</I>
|
|
|
|
resulted from a previous call to
|
|
<B>wordexp</B>(),
|
|
|
|
and
|
|
<B>wordfree</B>()
|
|
|
|
was not called.
|
|
Reuse the allocated storage.
|
|
<DT id="5"><B>WRDE_SHOWERR</B>
|
|
|
|
<DD>
|
|
Normally during command substitution
|
|
<I>stderr</I>
|
|
|
|
is redirected to
|
|
<I>/dev/null</I>.
|
|
|
|
This flag specifies that
|
|
<I>stderr</I>
|
|
|
|
is not to be redirected.
|
|
<DT id="6"><B>WRDE_UNDEF</B>
|
|
|
|
<DD>
|
|
Consider it an error if an undefined shell variable is expanded.
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
In case of success 0 is returned.
|
|
In case of error
|
|
one of the following five values is returned.
|
|
<DL COMPACT>
|
|
<DT id="7"><B>WRDE_BADCHAR</B>
|
|
|
|
<DD>
|
|
Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }.
|
|
<DT id="8"><B>WRDE_BADVAL</B>
|
|
|
|
<DD>
|
|
An undefined shell variable was referenced, and the
|
|
<B>WRDE_UNDEF</B>
|
|
|
|
flag
|
|
told us to consider this an error.
|
|
<DT id="9"><B>WRDE_CMDSUB</B>
|
|
|
|
<DD>
|
|
Command substitution requested, but the
|
|
<B>WRDE_NOCMD</B>
|
|
|
|
flag told us to consider this an error.
|
|
<DT id="10"><B>WRDE_NOSPACE</B>
|
|
|
|
<DD>
|
|
Out of memory.
|
|
<DT id="11"><B>WRDE_SYNTAX</B>
|
|
|
|
<DD>
|
|
Shell syntax error, such as unbalanced parentheses or
|
|
unmatched quotes.
|
|
</DL>
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>VERSIONS</H2>
|
|
|
|
<B>wordexp</B>()
|
|
|
|
and
|
|
<B>wordfree</B>()
|
|
|
|
are provided in glibc since version 2.1.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>ATTRIBUTES</H2>
|
|
|
|
For an explanation of the terms used in this section, see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+attributes">attributes</A></B>(7).
|
|
|
|
<TABLE BORDER>
|
|
<TR VALIGN=top><TD><B>Interface</B></TD><TD><B>Attribute</B></TD><TD><B>Value</B><BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>wordexp</B>()
|
|
|
|
</TD><TD>Thread safety</TD><TD>
|
|
MT-Unsafe race:utent const:env
|
|
<BR>
|
|
|
|
env sig:ALRM timer locale
|
|
<BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>wordfree</B>()
|
|
|
|
</TD><TD>Thread safety</TD><TD>MT-Safe<BR></TD></TR>
|
|
</TABLE>
|
|
|
|
<P>
|
|
In the above table,
|
|
<I>utent</I>
|
|
|
|
in
|
|
<I>race:utent</I>
|
|
|
|
signifies that if any of the functions
|
|
<B><A HREF="/cgi-bin/man/man2html?3+setutent">setutent</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+getutent">getutent</A></B>(3),
|
|
|
|
or
|
|
<B><A HREF="/cgi-bin/man/man2html?3+endutent">endutent</A></B>(3)
|
|
|
|
are used in parallel in different threads of a program,
|
|
then data races could occur.
|
|
<B>wordexp</B>()
|
|
|
|
calls those functions,
|
|
so we use race:utent to remind users.
|
|
<A NAME="lbAL"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
POSIX.1-2001, POSIX.1-2008.
|
|
<A NAME="lbAM"> </A>
|
|
<H2>EXAMPLE</H2>
|
|
|
|
The output of the following example program
|
|
is approximately that of "ls [a-c]*.c".
|
|
<P>
|
|
|
|
|
|
#include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>>
|
|
#include <<A HREF="file:///usr/include/stdlib.h">stdlib.h</A>>
|
|
#include <<A HREF="file:///usr/include/wordexp.h">wordexp.h</A>>
|
|
<P>
|
|
int
|
|
main(int argc, char **argv)
|
|
{
|
|
<BR> wordexp_t p;
|
|
<BR> char **w;
|
|
<BR> int i;
|
|
<P>
|
|
<BR> wordexp("[a-c]*.c", &p, 0);
|
|
<BR> w = p.we_wordv;
|
|
<BR> for (i = 0; i < p.we_wordc; i++)
|
|
<BR> printf("%s\n", w[i]);
|
|
<BR> wordfree(&p);
|
|
<BR> exit(EXIT_SUCCESS);
|
|
}
|
|
|
|
<A NAME="lbAN"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+fnmatch">fnmatch</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+glob">glob</A></B>(3)
|
|
|
|
<A NAME="lbAO"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="12"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="13"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="14"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="15"><A HREF="#lbAE">The string argument</A><DD>
|
|
<DT id="16"><A HREF="#lbAF">The expansion</A><DD>
|
|
<DT id="17"><A HREF="#lbAG">The output array</A><DD>
|
|
<DT id="18"><A HREF="#lbAH">The flags argument</A><DD>
|
|
</DL>
|
|
<DT id="19"><A HREF="#lbAI">RETURN VALUE</A><DD>
|
|
<DT id="20"><A HREF="#lbAJ">VERSIONS</A><DD>
|
|
<DT id="21"><A HREF="#lbAK">ATTRIBUTES</A><DD>
|
|
<DT id="22"><A HREF="#lbAL">CONFORMING TO</A><DD>
|
|
<DT id="23"><A HREF="#lbAM">EXAMPLE</A><DD>
|
|
<DT id="24"><A HREF="#lbAN">SEE ALSO</A><DD>
|
|
<DT id="25"><A HREF="#lbAO">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:00 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|