xref: /freebsd/lib/libc/gen/wordexp.3 (revision 89cead337af64e70a6ac854f01d2699afd83751c)
1faea1495STim J. Robbins.\"
2faea1495STim J. Robbins.\" Copyright (c) 2002 Tim J. Robbins
3faea1495STim J. Robbins.\" All rights reserved.
4faea1495STim J. Robbins.\"
5faea1495STim J. Robbins.\" Redistribution and use in source and binary forms, with or without
6faea1495STim J. Robbins.\" modification, are permitted provided that the following conditions
7faea1495STim J. Robbins.\" are met:
8faea1495STim J. Robbins.\" 1. Redistributions of source code must retain the above copyright
9faea1495STim J. Robbins.\"    notice, this list of conditions and the following disclaimer.
10faea1495STim J. Robbins.\" 2. Redistributions in binary form must reproduce the above copyright
11faea1495STim J. Robbins.\"    notice, this list of conditions and the following disclaimer in the
12faea1495STim J. Robbins.\"    documentation and/or other materials provided with the distribution.
13faea1495STim J. Robbins.\"
14faea1495STim J. Robbins.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15faea1495STim J. Robbins.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16faea1495STim J. Robbins.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17faea1495STim J. Robbins.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18faea1495STim J. Robbins.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19faea1495STim J. Robbins.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20faea1495STim J. Robbins.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21faea1495STim J. Robbins.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22faea1495STim J. Robbins.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23faea1495STim J. Robbins.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24faea1495STim J. Robbins.\" SUCH DAMAGE.
25faea1495STim J. Robbins.\"
26faea1495STim J. Robbins.\" $FreeBSD$
27faea1495STim J. Robbins.\"
282e8a0712SJilles Tjoelker.Dd August 18, 2015
29faea1495STim J. Robbins.Dt WORDEXP 3
30faea1495STim J. Robbins.Os
31faea1495STim J. Robbins.Sh NAME
32faea1495STim J. Robbins.Nm wordexp
33faea1495STim J. Robbins.Nd "perform shell-style word expansions"
34faea1495STim J. Robbins.Sh LIBRARY
35faea1495STim J. Robbins.Lb libc
36faea1495STim J. Robbins.Sh SYNOPSIS
37faea1495STim J. Robbins.In wordexp.h
38faea1495STim J. Robbins.Ft int
390e35e492SRuslan Ermilov.Fn wordexp "const char * restrict words" "wordexp_t * restrict we" "int flags"
40be074a2dSTim J. Robbins.Ft void
410e35e492SRuslan Ermilov.Fn wordfree "wordexp_t *we"
42faea1495STim J. Robbins.Sh DESCRIPTION
43faea1495STim J. RobbinsThe
44faea1495STim J. Robbins.Fn wordexp
45faea1495STim J. Robbinsfunction performs shell-style word expansion on
46faea1495STim J. Robbins.Fa words
47faea1495STim J. Robbinsand places the list of words into the
48faea1495STim J. Robbins.Va we_wordv
49faea1495STim J. Robbinsmember of
500e35e492SRuslan Ermilov.Fa we ,
51faea1495STim J. Robbinsand the number of words into
52faea1495STim J. Robbins.Va we_wordc .
53faea1495STim J. Robbins.Pp
54faea1495STim J. RobbinsThe
550e35e492SRuslan Ermilov.Fa flags
56faea1495STim J. Robbinsargument is the bitwise inclusive OR of any of the following constants:
57faea1495STim J. Robbins.Bl -tag -width ".Dv WRDE_SHOWERR"
58faea1495STim J. Robbins.It Dv WRDE_APPEND
590e35e492SRuslan ErmilovAppend the words to those generated by a previous call to
60faea1495STim J. Robbins.Fn wordexp .
61b7114d4aSTim J. Robbins.It Dv WRDE_DOOFFS
62faea1495STim J. RobbinsAs many
63faea1495STim J. Robbins.Dv NULL
64faea1495STim J. Robbinspointers as are specified by the
65faea1495STim J. Robbins.Va we_offs
66faea1495STim J. Robbinsmember of
670e35e492SRuslan Ermilov.Fa we
68faea1495STim J. Robbinsare added to the front of
69faea1495STim J. Robbins.Va we_wordv .
70faea1495STim J. Robbins.It Dv WRDE_NOCMD
71faea1495STim J. RobbinsDisallow command substitution in
72faea1495STim J. Robbins.Fa words .
73faea1495STim J. RobbinsSee the note in
74faea1495STim J. Robbins.Sx BUGS
75faea1495STim J. Robbinsbefore using this.
76faea1495STim J. Robbins.It Dv WRDE_REUSE
77faea1495STim J. RobbinsThe
780e35e492SRuslan Ermilov.Fa we
79faea1495STim J. Robbinsargument was passed to a previous successful call to
80faea1495STim J. Robbins.Fn wordexp
81faea1495STim J. Robbinsbut has not been passed to
82faea1495STim J. Robbins.Fn wordfree .
83faea1495STim J. RobbinsThe implementation may reuse the space allocated to it.
84faea1495STim J. Robbins.It Dv WRDE_SHOWERR
85faea1495STim J. RobbinsDo not redirect shell error messages to
86faea1495STim J. Robbins.Pa /dev/null .
87faea1495STim J. Robbins.It Dv WRDE_UNDEF
88faea1495STim J. RobbinsReport error on an attempt to expand an undefined shell variable.
89faea1495STim J. Robbins.El
90faea1495STim J. Robbins.Pp
91faea1495STim J. RobbinsThe
92faea1495STim J. Robbins.Vt wordexp_t
93faea1495STim J. Robbinsstructure is defined in
94fe08efe6SRuslan Ermilov.In wordexp.h
95faea1495STim J. Robbinsas:
96faea1495STim J. Robbins.Bd -literal -offset indent
97faea1495STim J. Robbinstypedef struct {
98faea1495STim J. Robbins	size_t	we_wordc;	/* count of words matched */
99faea1495STim J. Robbins	char	**we_wordv;	/* pointer to list of words */
100faea1495STim J. Robbins	size_t	we_offs;	/* slots to reserve in we_wordv */
101faea1495STim J. Robbins} wordexp_t;
102faea1495STim J. Robbins.Ed
103faea1495STim J. Robbins.Pp
104faea1495STim J. RobbinsThe
105faea1495STim J. Robbins.Fn wordfree
106faea1495STim J. Robbinsfunction frees the memory allocated by
107faea1495STim J. Robbins.Fn wordexp .
108faea1495STim J. Robbins.Sh IMPLEMENTATION NOTES
109faea1495STim J. RobbinsThe
110faea1495STim J. Robbins.Fn wordexp
1112e8a0712SJilles Tjoelkerfunction is implemented by executing
1122e8a0712SJilles Tjoelker.Xr sh 1 .
113faea1495STim J. Robbins.Sh RETURN VALUES
114faea1495STim J. RobbinsThe
115faea1495STim J. Robbins.Fn wordexp
116faea1495STim J. Robbinsfunction returns zero if successful, otherwise it returns one of the following
117faea1495STim J. Robbinserror codes:
118faea1495STim J. Robbins.Bl -tag -width ".Dv WRDE_NOSPACE"
119faea1495STim J. Robbins.It Dv WRDE_BADCHAR
120faea1495STim J. RobbinsThe
121faea1495STim J. Robbins.Fa words
122faea1495STim J. Robbinsargument contains one of the following unquoted characters:
1230e35e492SRuslan Ermilov.Aq newline ,
124faea1495STim J. Robbins.Ql | ,
125faea1495STim J. Robbins.Ql & ,
126faea1495STim J. Robbins.Ql \&; ,
127faea1495STim J. Robbins.Ql < ,
128faea1495STim J. Robbins.Ql > ,
129faea1495STim J. Robbins.Ql \&( ,
130faea1495STim J. Robbins.Ql \&) ,
131faea1495STim J. Robbins.Ql { ,
132faea1495STim J. Robbins.Ql } .
133faea1495STim J. Robbins.It Dv WRDE_BADVAL
134*89cead33SJilles TjoelkerAn error after successful parsing,
135*89cead33SJilles Tjoelkersuch as an attempt to expand an undefined shell variable with
136faea1495STim J. Robbins.Dv WRDE_UNDEF
137*89cead33SJilles Tjoelkerset in
138faea1495STim J. Robbins.Fa flags .
139faea1495STim J. Robbins.It Dv WRDE_CMDSUB
140faea1495STim J. RobbinsAn attempt was made to use command substitution and
141faea1495STim J. Robbins.Dv WRDE_NOCMD
142faea1495STim J. Robbinsis set in
143faea1495STim J. Robbins.Fa flags .
144faea1495STim J. Robbins.It Dv WRDE_NOSPACE
145*89cead33SJilles TjoelkerNot enough memory to store the result or
146*89cead33SJilles Tjoelkeran error during
147*89cead33SJilles Tjoelker.Xr fork 2 .
148faea1495STim J. Robbins.It Dv WRDE_SYNTAX
149faea1495STim J. RobbinsShell syntax error in
150faea1495STim J. Robbins.Fa words .
151faea1495STim J. Robbins.El
152faea1495STim J. Robbins.Pp
153faea1495STim J. RobbinsThe
154faea1495STim J. Robbins.Fn wordfree
155faea1495STim J. Robbinsfunction returns no value.
156faea1495STim J. Robbins.Sh ENVIRONMENT
157faea1495STim J. Robbins.Bl -tag -width ".Ev IFS"
158faea1495STim J. Robbins.It Ev IFS
159faea1495STim J. RobbinsField separator.
160faea1495STim J. Robbins.El
161faea1495STim J. Robbins.Sh EXAMPLES
162faea1495STim J. RobbinsInvoke the editor on all
1630e35e492SRuslan Ermilov.Pa .c
1640e35e492SRuslan Ermilovfiles in the current directory
165faea1495STim J. Robbinsand
166faea1495STim J. Robbins.Pa /etc/motd
167faea1495STim J. Robbins(error checking omitted):
168faea1495STim J. Robbins.Bd -literal -offset indent
169faea1495STim J. Robbinswordexp_t we;
170faea1495STim J. Robbins
171faea1495STim J. Robbinswordexp("${EDITOR:-vi} *.c /etc/motd", &we, 0);
172c499f23bSCeri Daviesexecvp(we.we_wordv[0], we.we_wordv);
173faea1495STim J. Robbins.Ed
174faea1495STim J. Robbins.Sh DIAGNOSTICS
175faea1495STim J. RobbinsDiagnostic messages from the shell are written to the standard error output
176faea1495STim J. Robbinsif
177faea1495STim J. Robbins.Dv WRDE_SHOWERR
178faea1495STim J. Robbinsis set in
179faea1495STim J. Robbins.Fa flags .
180faea1495STim J. Robbins.Sh SEE ALSO
181faea1495STim J. Robbins.Xr sh 1 ,
182faea1495STim J. Robbins.Xr fnmatch 3 ,
183faea1495STim J. Robbins.Xr glob 3 ,
184faea1495STim J. Robbins.Xr popen 3 ,
185faea1495STim J. Robbins.Xr system 3
186faea1495STim J. Robbins.Sh STANDARDS
187faea1495STim J. RobbinsThe
188faea1495STim J. Robbins.Fn wordexp
189faea1495STim J. Robbinsand
190faea1495STim J. Robbins.Fn wordfree
191cd203b8eSTim J. Robbinsfunctions conform to
192faea1495STim J. Robbins.St -p1003.1-2001 .
193faea1495STim J. Robbins.Sh BUGS
194faea1495STim J. RobbinsDo not pass untrusted user data to
195faea1495STim J. Robbins.Fn wordexp ,
196faea1495STim J. Robbinsregardless of whether the
197faea1495STim J. Robbins.Dv WRDE_NOCMD
198faea1495STim J. Robbinsflag is set.
199faea1495STim J. RobbinsThe
200faea1495STim J. Robbins.Fn wordexp
201faea1495STim J. Robbinsfunction attempts to detect input that would cause commands to be
202faea1495STim J. Robbinsexecuted before passing it to the shell
203faea1495STim J. Robbinsbut it does not use the same parser so it may be fooled.
204f825dd29STim J. Robbins.Pp
205f825dd29STim J. RobbinsThe current
206f825dd29STim J. Robbins.Fn wordexp
207d7852cbcSBaptiste Daroussinimplementation does not recognize multibyte characters other than UTF-8, since
208d7852cbcSBaptiste Daroussinthe shell (which it invokes to perform expansions) does not.
209