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