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