2 .\" Copyright (c) 2002 Tim J. Robbins
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .Dd September 30, 2015
33 .Nd "perform shell-style word expansions"
39 .Fn wordexp "const char * restrict words" "wordexp_t * restrict we" "int flags"
41 .Fn wordfree "wordexp_t *we"
45 function performs shell-style word expansion on
47 and places the list of words into the
51 and the number of words into
56 argument is the bitwise inclusive OR of any of the following constants:
57 .Bl -tag -width ".Dv WRDE_SHOWERR"
59 Append the words to those generated by a previous call to
64 pointers as are specified by the
68 are added to the front of
71 Disallow command substitution in
79 argument was passed to a previous successful call to
81 but has not been passed to
83 The implementation may reuse the space allocated to it.
85 Do not redirect shell error messages to
88 Report error on an attempt to expand an undefined shell variable.
93 structure is defined in
96 .Bd -literal -offset indent
98 size_t we_wordc; /* count of words matched */
99 char **we_wordv; /* pointer to list of words */
100 size_t we_offs; /* slots to reserve in we_wordv */
106 function frees the memory allocated by
108 .Sh IMPLEMENTATION NOTES
111 function is implemented using the undocumented
113 shell built-in command.
117 function returns zero if successful, otherwise it returns one of the following
119 .Bl -tag -width ".Dv WRDE_NOSPACE"
123 argument contains one of the following unquoted characters:
135 An attempt was made to expand an undefined shell variable and
140 An attempt was made to use command substitution and
145 Not enough memory to store the result.
147 Shell syntax error in
153 function returns no value.
155 .Bl -tag -width ".Ev IFS"
160 Invoke the editor on all
162 files in the current directory
165 (error checking omitted):
166 .Bd -literal -offset indent
169 wordexp("${EDITOR:-vi} *.c /etc/motd", &we, 0);
170 execvp(we.we_wordv[0], we.we_wordv);
173 Diagnostic messages from the shell are written to the standard error output
194 implementation does not recognize multibyte characters other than UTF-8, since
195 the shell (which it invokes to perform expansions) does not.
196 .Sh SECURITY CONSIDERATIONS
197 Pathname generation may create output that is exponentially larger than the
200 Although this implementation detects command substitution reliably for
202 the attack surface remains fairly large.
203 Also, some other implementations
204 (such as older versions of this one)
205 may execute command substitutions even if