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 July 29, 2004 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 as a wrapper around the undocumented 112.Ic wordexp 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 attempt was made to expand an undefined shell variable and 136.Dv WRDE_UNDEF 137is set 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. 146.It Dv WRDE_SYNTAX 147Shell syntax error in 148.Fa words . 149.El 150.Pp 151The 152.Fn wordfree 153function returns no value. 154.Sh ENVIRONMENT 155.Bl -tag -width ".Ev IFS" 156.It Ev IFS 157Field separator. 158.El 159.Sh EXAMPLES 160Invoke the editor on all 161.Pa .c 162files in the current directory 163and 164.Pa /etc/motd 165(error checking omitted): 166.Bd -literal -offset indent 167wordexp_t we; 168 169wordexp("${EDITOR:-vi} *.c /etc/motd", &we, 0); 170execvp(we.we_wordv[0], we.we_wordv); 171.Ed 172.Sh DIAGNOSTICS 173Diagnostic messages from the shell are written to the standard error output 174if 175.Dv WRDE_SHOWERR 176is set in 177.Fa flags . 178.Sh SEE ALSO 179.Xr sh 1 , 180.Xr fnmatch 3 , 181.Xr glob 3 , 182.Xr popen 3 , 183.Xr system 3 184.Sh STANDARDS 185The 186.Fn wordexp 187and 188.Fn wordfree 189functions conform to 190.St -p1003.1-2001 . 191.Sh BUGS 192Do not pass untrusted user data to 193.Fn wordexp , 194regardless of whether the 195.Dv WRDE_NOCMD 196flag is set. 197The 198.Fn wordexp 199function attempts to detect input that would cause commands to be 200executed before passing it to the shell 201but it does not use the same parser so it may be fooled. 202.Pp 203The current 204.Fn wordexp 205implementation does not recognize multibyte characters, since the 206shell (which it invokes to perform expansions) does not. 207