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 December 27, 2002 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.Fo wordexp 40.Fa "const char * restrict words" 41.Fa "wordexp_t * restrict we" 42.Fa "int flags" 43.Fc 44.Fo wordfree 45.Fa "wordexp_t *we" 46.Fc 47.Sh DESCRIPTION 48The 49.Fn wordexp 50function performs shell-style word expansion on 51.Fa words 52and places the list of words into the 53.Va we_wordv 54member of 55.Va we , 56and the number of words into 57.Va we_wordc . 58.Pp 59The 60.Va flags 61argument is the bitwise inclusive OR of any of the following constants: 62.Bl -tag -width ".Dv WRDE_SHOWERR" 63.It Dv WRDE_APPEND 64Append the words to those generate by a previous call to 65.Fn wordexp . 66.It Dv WRDE_DOOFS 67As many 68.Dv NULL 69pointers as are specified by the 70.Va we_offs 71member of 72.Va we 73are added to the front of 74.Va we_wordv . 75.It Dv WRDE_NOCMD 76Disallow command substitution in 77.Fa words . 78See the note in 79.Sx BUGS 80before using this. 81.It Dv WRDE_REUSE 82The 83.Va we 84argument was passed to a previous successful call to 85.Fn wordexp 86but has not been passed to 87.Fn wordfree . 88The implementation may reuse the space allocated to it. 89.It Dv WRDE_SHOWERR 90Do not redirect shell error messages to 91.Pa /dev/null . 92.It Dv WRDE_UNDEF 93Report error on an attempt to expand an undefined shell variable. 94.El 95.Pp 96The 97.Vt wordexp_t 98structure is defined in 99.Pa wordexp.h 100as: 101.Bd -literal -offset indent 102typedef struct { 103 size_t we_wordc; /* count of words matched */ 104 char **we_wordv; /* pointer to list of words */ 105 size_t we_offs; /* slots to reserve in we_wordv */ 106} wordexp_t; 107.Ed 108.Pp 109The 110.Fn wordfree 111function frees the memory allocated by 112.Fn wordexp . 113.Sh IMPLEMENTATION NOTES 114The 115.Fn wordexp 116function is implemented as a wrapper around the undocumented 117.Ic wordexp 118shell built-in command. 119.Sh RETURN VALUES 120The 121.Fn wordexp 122function returns zero if successful, otherwise it returns one of the following 123error codes: 124.Bl -tag -width ".Dv WRDE_NOSPACE" 125.It Dv WRDE_BADCHAR 126The 127.Fa words 128argument contains one of the following unquoted characters: 129<newline>, 130.Ql | , 131.Ql & , 132.Ql \&; , 133.Ql < , 134.Ql > , 135.Ql \&( , 136.Ql \&) , 137.Ql { , 138.Ql } . 139.It Dv WRDE_BADVAL 140An attempt was made to expand an undefined shell variable and 141.Dv WRDE_UNDEF 142is set in 143.Fa flags . 144.It Dv WRDE_CMDSUB 145An attempt was made to use command substitution and 146.Dv WRDE_NOCMD 147is set in 148.Fa flags . 149.It Dv WRDE_NOSPACE 150Not enough memory to store the result. 151.It Dv WRDE_SYNTAX 152Shell syntax error in 153.Fa words . 154.El 155.Pp 156The 157.Fn wordfree 158function returns no value. 159.Sh ENVIRONMENT 160.Bl -tag -width ".Ev IFS" 161.It Ev IFS 162Field separator. 163.El 164.Sh EXAMPLES 165Invoke the editor on all 166.Dq Li \&.c 167files in the current directory, 168and 169.Pa /etc/motd 170(error checking omitted): 171.Bd -literal -offset indent 172wordexp_t we; 173 174wordexp("${EDITOR:-vi} *.c /etc/motd", &we, 0); 175execvp(we->we_wordv[0], we->we_wordv); 176.Ed 177.Sh DIAGNOSTICS 178Diagnostic messages from the shell are written to the standard error output 179if 180.Dv WRDE_SHOWERR 181is set in 182.Fa flags . 183.Sh SEE ALSO 184.Xr sh 1 , 185.Xr fnmatch 3 , 186.Xr glob 3 , 187.Xr popen 3 , 188.Xr system 3 189.Sh STANDARDS 190The 191.Fn wordexp 192and 193.Fn wordfree 194functions conform to 195.St -p1003.1-2001 . 196.Sh BUGS 197Do not pass untrusted user data to 198.Fn wordexp , 199regardless of whether the 200.Dv WRDE_NOCMD 201flag is set. 202The 203.Fn wordexp 204function attempts to detect input that would cause commands to be 205executed before passing it to the shell 206but it does not use the same parser so it may be fooled. 207