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$ 27.\" 28.Dd August 18, 2015 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 by executing 112.Xr sh 1 . 113.Sh RETURN VALUES 114The 115.Fn wordexp 116function returns zero if successful, otherwise it returns one of the following 117error codes: 118.Bl -tag -width ".Dv WRDE_NOSPACE" 119.It Dv WRDE_BADCHAR 120The 121.Fa words 122argument contains one of the following unquoted characters: 123.Aq newline , 124.Ql | , 125.Ql & , 126.Ql \&; , 127.Ql < , 128.Ql > , 129.Ql \&( , 130.Ql \&) , 131.Ql { , 132.Ql } . 133.It Dv WRDE_BADVAL 134An error after successful parsing, 135such as an attempt to expand an undefined shell variable with 136.Dv WRDE_UNDEF 137set in 138.Fa flags . 139.It Dv WRDE_CMDSUB 140An attempt was made to use command substitution and 141.Dv WRDE_NOCMD 142is set in 143.Fa flags . 144.It Dv WRDE_NOSPACE 145Not enough memory to store the result or 146an error during 147.Xr fork 2 . 148.It Dv WRDE_SYNTAX 149Shell syntax error in 150.Fa words . 151.El 152.Pp 153The 154.Fn wordfree 155function returns no value. 156.Sh ENVIRONMENT 157.Bl -tag -width ".Ev IFS" 158.It Ev IFS 159Field separator. 160.El 161.Sh EXAMPLES 162Invoke the editor on all 163.Pa .c 164files in the current directory 165and 166.Pa /etc/motd 167(error checking omitted): 168.Bd -literal -offset indent 169wordexp_t we; 170 171wordexp("${EDITOR:-vi} *.c /etc/motd", &we, 0); 172execvp(we.we_wordv[0], we.we_wordv); 173.Ed 174.Sh DIAGNOSTICS 175Diagnostic messages from the shell are written to the standard error output 176if 177.Dv WRDE_SHOWERR 178is set in 179.Fa flags . 180.Sh SEE ALSO 181.Xr sh 1 , 182.Xr fnmatch 3 , 183.Xr glob 3 , 184.Xr popen 3 , 185.Xr system 3 186.Sh STANDARDS 187The 188.Fn wordexp 189and 190.Fn wordfree 191functions conform to 192.St -p1003.1-2001 . 193.Sh BUGS 194Do not pass untrusted user data to 195.Fn wordexp , 196regardless of whether the 197.Dv WRDE_NOCMD 198flag is set. 199The 200.Fn wordexp 201function attempts to detect input that would cause commands to be 202executed before passing it to the shell 203but it does not use the same parser so it may be fooled. 204.Pp 205The current 206.Fn wordexp 207implementation does not recognize multibyte characters other than UTF-8, since 208the shell (which it invokes to perform expansions) does not. 209