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