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