1wordexp(3C)              Standard C Library Functions              wordexp(3C)
2
3
4

NAME

6       wordexp, wordfree - perform word expansions
7

SYNOPSIS

9       #include <wordexp.h>
10
11       int wordexp(const char *restrict words, wordexp_t *restrict pwordexp,
12            int flags);
13
14
15       void wordfree(wordexp_t *pwordexp);
16
17

DESCRIPTION

19       The  wordexp()  function  performs word expansions, subject to quoting,
20       and places the list of expanded words into the structure pointed to  by
21       pwordexp.
22
23
24       The wordfree() function frees any memory allocated by wordexp() associ‐
25       ated with pwordexp.
26
27   words Argument
28       The words argument is a pointer to a  string  containing  one  or  more
29       words  to be expanded. The expansions will be the same as would be per‐
30       formed by the shell if words were the part of a command line represent‐
31       ing  the  arguments  to a utility. Therefore, words must not contain an
32       unquoted NEWLINE or any of the unquoted shell special characters:
33
34
35        |   &   ;   <   >
36
37
38       except in the context of command substitution. It also must not contain
39       unquoted  parentheses  or  braces,  except in the context of command or
40       variable substitution. If the argument words contains an unquoted  com‐
41       ment  character  (number  sign) that is the beginning of a token, word‐
42       exp() may treat the comment character as a regular  character,  or  may
43       interpret it as a comment indicator and ignore the remainder of words.
44
45   pwordexp Argument
46       The  structure  type wordexp_t is defined in the header <wordexp.h> and
47       includes at least the following members:
48
49       size_t we_wordc    Count of words matched by words.
50
51
52       char **we_wordv    Pointer to list of expanded words.
53
54
55       size_t we_offs     Slots  to  reserve  at  the  beginning   of   pword‐
56                          exp−>we_wordv.
57
58
59
60       The wordexp() function stores the number of generated words into pword‐
61       exp−>we_wordc and a pointer to a list of pointers to  words  in  pword‐
62       exp−>we_wordv.  Each individual field created during field splitting is
63       a separate word in the  pwordexp−>we_wordv  list.   The  words  are  in
64       order.  The  first  pointer  after the last word pointer will be a null
65       pointer.
66
67
68       It is the caller's responsibility to allocate the storage pointed to by
69       pwordexp.  The  wordexp()  function  allocates  other  space as needed,
70       including memory pointed to by pwordexp−>we_wordv. The wordfree() func‐
71       tion  frees any memory associated with pwordexp from a previous call to
72       wordexp().
73
74   flags Argument
75       The flags argument is used to control the behavior  of  wordexp().  The
76       value  of flags is the bitwise inclusive OR of zero or more of the fol‐
77       lowing constants, which are defined in <wordexp.h>:
78
79       WRDE_APPEND     Append words generated to the ones from a previous call
80                       to wordexp().
81
82
83       WRDE_DOOFFS     Make  use  of  pwordexp−>we_offs.  If this flag is set,
84                       pwordexp−>we_offs is used  to  specify  how  many  NULL
85                       pointers to add to the beginning of pwordexp−>we_wordv.
86                       In other words, pwordexp−>we_wordv will point to pword‐
87                       exp−>we_offs   NULL   pointers,   followed   by  pword‐
88                       exp−>we_wordc  word  pointers,  followed  by   a   NULL
89                       pointer.
90
91
92       WRDE_NOCMD      Fail if command substitution is requested.
93
94
95       WRDE_REUSE      The pwordexp argument was passed to a previous success‐
96                       ful call to wordexp(), and has not been passed to word‐
97                       free().  The result will be the same as if the applica‐
98                       tion had called wordfree() and  then  called  wordexp()
99                       without WRDE_REUSE.
100
101
102       WRDE_SHOWERR    Do not redirect stderr to /dev/null.
103
104
105       WRDE_UNDEF      Report error on an attempt to expand an undefined shell
106                       variable.
107
108
109
110       The WRDE_APPEND flag can be used to append a new set of words to  those
111       generated  by  a  previous call to wordexp(). The following rules apply
112       when two or more calls to wordexp() are made with  the  same  value  of
113       pwordexp and without intervening calls to wordfree():
114
115           1.     The first such call must not set WRDE_APPEND. All subsequent
116                  calls must set it.
117
118           2.     All of the calls must set WRDE_DOOFFS, or all must  not  set
119                  it.
120
121           3.     After   the   second   and   each  subsequent  call,  pword‐
122                  exp−>we_wordv will point to a list containing the following:
123
124               a.     zero or more NULL pointers, as specified by  WRDE_DOOFFS
125                      and pwordexp−>we_offs.
126
127               b.     pointers   to   the   words  that  were  in  the  pword‐
128                      exp−>we_wordv list before the call, in the same order as
129                      before.
130
131               c.     pointers  to the new words generated by the latest call,
132                      in the specified order.
133
134           4.     The count returned in pwordexp−>we_wordc will be  the  total
135                  number of words from all of the calls.
136
137           5.     The application can change any of the fields after a call to
138                  wordexp(), but if it does it must reset them to the original
139                  value  before  a  subsequent  call,  using the same pwordexp
140                  value, to wordfree() or wordexp() with  the  WRDE_APPEND  or
141                  WRDE_REUSE flag.
142
143
144       If words contains an unquoted:
145
146
147       NEWLINE |   &   ;   <   >   (   )   {   }
148
149
150       in  an  inappropriate  context,  wordexp() will fail, and the number of
151       expanded words will be zero.
152
153
154       Unless WRDE_SHOWERR is set in flags, wordexp() will redirect stderr  to
155       /dev/null  for  any utilities executed as a result of command substitu‐
156       tion while expanding words.
157
158
159       If WRDE_SHOWERR is set, wordexp() may write messages to stderr if  syn‐
160       tax  errors  are detected while expanding words. If WRDE_DOOFFS is set,
161       then pwordexp−> we_offs must have the same  value  for  each  wordexp()
162       call and wordfree() call using a given pwordexp.
163
164
165       The following constants are defined as error return values:
166
167       WRDE_BADCHAR    One of the unquoted characters:
168
169                       NEWLINE |   &   ;   <   >   (   )   {   }
170
171                       appears in words in an inappropriate context.
172
173
174       WRDE_BADVAL     Reference  to  undefined shell variable when WRDE_UNDEF
175                       is set in flags.
176
177
178       WRDE_CMDSUB     Command substitution requested when WRDE_NOCMD was  set
179                       in flags.
180
181
182       WRDE_NOSPACE    Attempt to allocate memory failed.
183
184
185       WRDE_SYNTAX     Shell  syntax  error, such as unbalanced parentheses or
186                       unterminated string.
187
188

RETURN VALUES

190       On successful completion, wordexp() returns 0.
191
192
193       Otherwise, a non-zero value as described in <wordexp.h> is returned  to
194       indicate  an  error.  If wordexp() returns the value WRDE_NOSPACE, then
195       pwordexp−>we_wordc and pwordexp−>we_wordv will be  updated  to  reflect
196       any  words  that  were successfully expanded. In other cases, they will
197       not be modified.
198
199
200       The wordfree() function returns no value.
201

ERRORS

203       No errors are defined.
204

USAGE

206       This function is intended to be used by an application that wants to do
207       all  of the shell's expansions on a word or words obtained from a user.
208       For example, if the application prompts for  a  filename  (or  list  of
209       filenames) and then uses wordexp() to process the input, the user could
210       respond with anything that would be valid as input to the shell.
211
212
213       The WRDE_NOCMD flag is provided for applications that, for security  or
214       other  reasons,  want  to  prevent a user from executing shell command.
215       Disallowing unquoted shell special characters  also  prevents  unwanted
216       side effects such as executing a command or writing a file.
217

ATTRIBUTES

219       See attributes(5) for descriptions of the following attributes:
220
221
222
223
224       ┌─────────────────────────────┬─────────────────────────────┐
225       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
226       ├─────────────────────────────┼─────────────────────────────┤
227       │Interface Stability          │Standard                     │
228       ├─────────────────────────────┼─────────────────────────────┤
229       │MT-Level                     │MT-Safe                      │
230       └─────────────────────────────┴─────────────────────────────┘
231

SEE ALSO

233       fnmatch(3C), glob(3C), attributes(5), standards(5)
234
235
236
237SunOS 5.11                        1 Nov 2003                       wordexp(3C)
Impressum