1.\" 2.\" Copyright (c) 2002 Tim J. Robbins 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 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. 13.\" 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 24.\" SUCH DAMAGE. 25.\" 26.Dd September 30, 2015 27.Dt WORDEXP 3 28.Os 29.Sh NAME 30.Nm wordexp 31.Nd "perform shell-style word expansions" 32.Sh LIBRARY 33.Lb libc 34.Sh SYNOPSIS 35.In wordexp.h 36.Ft int 37.Fn wordexp "const char * restrict words" "wordexp_t * restrict we" "int flags" 38.Ft void 39.Fn wordfree "wordexp_t *we" 40.Sh DESCRIPTION 41The 42.Fn wordexp 43function performs shell-style word expansion on 44.Fa words 45and places the list of words into the 46.Va we_wordv 47member of 48.Fa we , 49and the number of words into 50.Va we_wordc . 51.Pp 52The 53.Fa flags 54argument is the bitwise inclusive OR of any of the following constants: 55.Bl -tag -width ".Dv WRDE_SHOWERR" 56.It Dv WRDE_APPEND 57Append the words to those generated by a previous call to 58.Fn wordexp . 59.It Dv WRDE_DOOFFS 60As many 61.Dv NULL 62pointers as are specified by the 63.Va we_offs 64member of 65.Fa we 66are added to the front of 67.Va we_wordv . 68.It Dv WRDE_NOCMD 69Disallow command substitution in 70.Fa words . 71See the note in 72.Sx BUGS 73before using this. 74.It Dv WRDE_REUSE 75The 76.Fa we 77argument was passed to a previous successful call to 78.Fn wordexp 79but has not been passed to 80.Fn wordfree . 81The implementation may reuse the space allocated to it. 82.It Dv WRDE_SHOWERR 83Do not redirect shell error messages to 84.Pa /dev/null . 85.It Dv WRDE_UNDEF 86Report error on an attempt to expand an undefined shell variable. 87.El 88.Pp 89The 90.Vt wordexp_t 91structure is defined in 92.In wordexp.h 93as: 94.Bd -literal -offset indent 95typedef struct { 96 size_t we_wordc; /* count of words matched */ 97 char **we_wordv; /* pointer to list of words */ 98 size_t we_offs; /* slots to reserve in we_wordv */ 99} wordexp_t; 100.Ed 101.Pp 102The 103.Fn wordfree 104function frees the memory allocated by 105.Fn wordexp . 106.Sh IMPLEMENTATION NOTES 107The 108.Fn wordexp 109function is implemented using the undocumented 110.Ic freebsd_wordexp 111shell built-in command. 112.Sh RETURN VALUES 113The 114.Fn wordexp 115function returns zero if successful, otherwise it returns one of the following 116error codes: 117.Bl -tag -width ".Dv WRDE_NOSPACE" 118.It Dv WRDE_BADCHAR 119The 120.Fa words 121argument contains one of the following unquoted characters: 122.Aq newline , 123.Ql | , 124.Ql & , 125.Ql \&; , 126.Ql < , 127.Ql > , 128.Ql \&( , 129.Ql \&) , 130.Ql { , 131.Ql } . 132.It Dv WRDE_BADVAL 133An error after successful parsing, 134such as an attempt to expand an undefined shell variable with 135.Dv WRDE_UNDEF 136set in 137.Fa flags . 138.It Dv WRDE_CMDSUB 139An attempt was made to use command substitution and 140.Dv WRDE_NOCMD 141is set in 142.Fa flags . 143.It Dv WRDE_NOSPACE 144Not enough memory to store the result or 145an error during 146.Xr fork 2 . 147.It Dv WRDE_SYNTAX 148Shell syntax error in 149.Fa words . 150.El 151.Pp 152The 153.Fn wordfree 154function returns no value. 155.Sh ENVIRONMENT 156.Bl -tag -width ".Ev IFS" 157.It Ev IFS 158Field separator. 159.El 160.Sh EXAMPLES 161Invoke the editor on all 162.Pa .c 163files in the current directory 164and 165.Pa /etc/motd 166(error checking omitted): 167.Bd -literal -offset indent 168wordexp_t we; 169 170wordexp("${EDITOR:-vi} *.c /etc/motd", &we, 0); 171execvp(we.we_wordv[0], we.we_wordv); 172.Ed 173.Sh DIAGNOSTICS 174Diagnostic messages from the shell are written to the standard error output 175if 176.Dv WRDE_SHOWERR 177is set in 178.Fa flags . 179.Sh SEE ALSO 180.Xr sh 1 , 181.Xr fnmatch 3 , 182.Xr glob 3 , 183.Xr popen 3 , 184.Xr system 3 185.Sh STANDARDS 186The 187.Fn wordexp 188and 189.Fn wordfree 190functions conform to 191.St -p1003.1-2001 . 192.Sh BUGS 193The current 194.Fn wordexp 195implementation does not recognize multibyte characters other than UTF-8, since 196the shell (which it invokes to perform expansions) does not. 197.Sh SECURITY CONSIDERATIONS 198Pathname generation may create output that is exponentially larger than the 199input size. 200.Pp 201Although this implementation detects command substitution reliably for 202.Dv WRDE_NOCMD , 203the attack surface remains fairly large. 204Also, some other implementations 205(such as older versions of this one) 206may execute command substitutions even if 207.Dv WRDE_NOCMD 208is set. 209