1WORDEXP(P)                 POSIX Programmer's Manual                WORDEXP(P)
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       void wordfree(wordexp_t *pwordexp);
14
15

DESCRIPTION

17       The  wordexp()  function  shall perform word expansions as described in
18       the Shell and Utilities volume of  IEEE Std 1003.1-2001,  Section  2.6,
19       Word  Expansions, subject to quoting as in the Shell and Utilities vol‐
20       ume of IEEE Std 1003.1-2001, Section 2.2, Quoting, and place  the  list
21       of expanded words into the structure pointed to by pwordexp.
22
23       The  words  argument  is  a  pointer to a string containing one or more
24       words to be expanded. The expansions shall be the same as would be per‐
25       formed by the command line interpreter if words were the part of a com‐
26       mand line representing the  arguments  to  a  utility.  Therefore,  the
27       application  shall ensure that words does not contain an unquoted <new‐
28       line> or any of the unquoted shell special characters '|' , '&' , ';' ,
29       '<' , '>' except in the context of command substitution as specified in
30       the Shell and Utilities volume of IEEE Std 1003.1-2001, Section  2.6.3,
31       Command  Substitution.   It also shall not contain unquoted parentheses
32       or braces, except in the context of command or  variable  substitution.
33       The  application  shall  ensure  that  every  member  of words which it
34       expects to have expanded by wordexp() does not contain an unquoted ini‐
35       tial  comment  character.  The  application  shall also ensure that any
36       words which it intends to be ignored (because they begin or continue  a
37       comment)  are  deleted  from  words.  If the argument words contains an
38       unquoted comment character (number sign) that is  the  beginning  of  a
39       token,  wordexp() shall either treat the comment character as a regular
40       character, or interpret it  as  a  comment  indicator  and  ignore  the
41       remainder of words.
42
43       The  structure  type wordexp_t is defined in the <wordexp.h> header and
44       includes at least the following members:
45
46          Member Type Member Name Description
47          size_t      we_wordc    Count of words matched by words.
48          char **     we_wordv    Pointer to list of expanded words.
49          size_t      we_offs     Slots to reserve at the beginning of
50                                  pwordexp->we_wordv.
51
52       The  wordexp()  function shall store the number of generated words into
53       pwordexp->we_wordc and a pointer to a list  of  pointers  to  words  in
54       pwordexp->we_wordv.   Each individual field created during field split‐
55       ting (see the Shell and Utilities volume of IEEE Std 1003.1-2001,  Sec‐
56       tion  2.6.5,  Field Splitting) or pathname expansion (see the Shell and
57       Utilities  volume  of  IEEE Std 1003.1-2001,  Section  2.6.6,  Pathname
58       Expansion) shall be a separate word in the pwordexp->we_wordv list. The
59       words shall be in order as described in the Shell and Utilities  volume
60       of  IEEE Std 1003.1-2001,  Section  2.6,  Word  Expansions.  The  first
61       pointer after the last word pointer shall be a null pointer. The expan‐
62       sion  of special parameters described in the Shell and Utilities volume
63       of IEEE Std 1003.1-2001, Section 2.5.2, Special Parameters is  unspeci‐
64       fied.
65
66       It is the caller's responsibility to allocate the storage pointed to by
67       pwordexp. The wordexp() function shall allocate other space as  needed,
68       including  memory  pointed  to  by  pwordexp->we_wordv.  The wordfree()
69       function frees any memory associated with pwordexp from a previous call
70       to wordexp().
71
72       The  flags  argument is used to control the behavior of wordexp().  The
73       value of flags is the bitwise-inclusive OR of zero or more of the  fol‐
74       lowing constants, which are defined in <wordexp.h>:
75
76       WRDE_APPEND
77              Append words generated to the ones from a previous call to word‐
78              exp().
79
80       WRDE_DOOFFS
81              Make use of pwordexp->we_offs.  If  this  flag  is  set,  pword‐
82              exp->we_offs is used to specify how many null pointers to add to
83              the beginning of pwordexp->we_wordv.   In  other  words,  pword‐
84              exp->we_wordv  shall  point  to pwordexp->we_offs null pointers,
85              followed by pwordexp->we_wordc word pointers, followed by a null
86              pointer.
87
88       WRDE_NOCMD
89              If  the  implementation  supports  the  utilities defined in the
90              Shell and Utilities volume of IEEE Std 1003.1-2001, fail if com‐
91              mand  substitution, as specified in the Shell and Utilities vol‐
92              ume of IEEE Std 1003.1-2001, Section  2.6.3,  Command  Substitu‐
93              tion, is requested.
94
95       WRDE_REUSE
96              The  pwordexp  argument was passed to a previous successful call
97              to wordexp(), and has not been passed to wordfree(). The  result
98              shall  be  the  same as if the application had called wordfree()
99              and then called wordexp() without WRDE_REUSE.
100
101       WRDE_SHOWERR
102              Do not redirect stderr to /dev/null.
103
104       WRDE_UNDEF
105              Report error on an attempt to expand an  undefined  shell  vari‐
106              able.
107
108
109       The  WRDE_APPEND flag can be used to append a new set of words to those
110       generated by a previous call to wordexp(). The following rules apply to
111       applications when two or more calls to wordexp() are made with the same
112       value of pwordexp and without intervening calls to wordfree():
113
114        1. The first such call shall not set WRDE_APPEND. All subsequent calls
115           shall set it.
116
117        2. All of the calls shall set WRDE_DOOFFS, or all shall not set it.
118
119        3. After the second and each subsequent call, pwordexp->we_wordv shall
120           point to a list containing the following:
121
122            a. Zero or more null pointers, as  specified  by  WRDE_DOOFFS  and
123               pwordexp->we_offs
124
125            b. Pointers  to the words that were in the pwordexp->we_wordv list
126               before the call, in the same order as before
127
128            c. Pointers to the new words generated by the latest call, in  the
129               specified order
130
131        4. The  count returned in pwordexp->we_wordc shall be the total number
132           of words from all of the calls.
133
134        5. The application can change any of the fields after a call to  word‐
135           exp(),  but  if  it  does it shall reset them to the original value
136           before a subsequent call, using the same pwordexp value,  to  word‐
137           free() or wordexp() with the WRDE_APPEND or WRDE_REUSE flag.
138
139       If  the  implementation supports the utilities defined in the Shell and
140       Utilities  volume  of  IEEE Std 1003.1-2001,  and  words  contains   an
141       unquoted  character- <newline>, '|' , '&' , ';' , '<' , '>' , '(' , ')'
142       , '{' , '}' - in an inappropriate context, wordexp()  shall  fail,  and
143       the number of expanded words shall be 0.
144
145       Unless WRDE_SHOWERR is set in flags, wordexp() shall redirect stderr to
146       /dev/null for any utilities executed as a result of  command  substitu‐
147       tion  while  expanding  words.   If  WRDE_SHOWERR is set, wordexp() may
148       write messages to stderr if syntax errors are detected while  expanding
149       words.
150
151       The  application  shall  ensure that if WRDE_DOOFFS is set, then pword‐
152       exp->we_offs has the same value for each wordexp() call and  wordfree()
153       call using a given pwordexp.
154
155       The following constants are defined as error return values:
156
157       WRDE_BADCHAR
158              One of the unquoted characters- <newline>, '|' , '&' , ';' , '<'
159              , '>' , '(' , ')' , '{' , '}' - appears in words in an  inappro‐
160              priate context.
161
162       WRDE_BADVAL
163              Reference  to undefined shell variable when WRDE_UNDEF is set in
164              flags.
165
166       WRDE_CMDSUB
167              Command substitution requested when WRDE_NOCMD was set in flags.
168
169       WRDE_NOSPACE
170              Attempt to allocate memory failed.
171
172       WRDE_SYNTAX
173              Shell syntax error, such as unbalanced parentheses  or  untermi‐
174              nated string.
175
176

RETURN VALUE

178       Upon successful completion, wordexp() shall return 0. Otherwise, a non-
179       zero value, as described in <wordexp.h>, shall be returned to  indicate
180       an  error.  If  wordexp()  returns  the value WRDE_NOSPACE, then pword‐
181       exp->we_wordc and pwordexp->we_wordv shall be updated  to  reflect  any
182       words  that  were successfully expanded. In other cases, they shall not
183       be modified.
184
185       The wordfree() function shall not return a value.
186

ERRORS

188       No errors are defined.
189
190       The following sections are informative.
191

EXAMPLES

193       None.
194

APPLICATION USAGE

196       The wordexp() function is intended to be used by  an  application  that
197       wants  to  do all of the shell's expansions on a word or words obtained
198       from a user. For example, if the application prompts for a filename (or
199       list  of  filenames)  and then uses wordexp() to process the input, the
200       user could respond with anything that would be valid as  input  to  the
201       shell.
202
203       The  WRDE_NOCMD flag is provided for applications that, for security or
204       other reasons, want to prevent a user from  executing  shell  commands.
205       Disallowing  unquoted  shell  special characters also prevents unwanted
206       side effects, such as executing a command or writing a file.
207

RATIONALE

209       This function was included as an alternative to glob(). There had  been
210       continuing controversy over exactly what features should be included in
211       glob().  It is hoped that by providing wordexp() (which provides all of
212       the shell word expansions, but which may be slow to execute) and glob()
213       (which is faster, but which only performs pathname  expansion,  without
214       tilde  or parameter expansion) this will satisfy the majority of appli‐
215       cations.
216
217       While wordexp() could be implemented entirely as a library routine,  it
218       is expected that most implementations run a shell in a subprocess to do
219       the expansion.
220
221       Two different approaches have been proposed for how the required infor‐
222       mation  might  be presented to the shell and the results returned. They
223       are presented here as examples.
224
225       One proposal is to extend the echo utility by adding a -q option.  This
226       option  would  cause  echo to add a backslash before each backslash and
227       <blank> that occurs within an argument. The  wordexp()  function  could
228       then invoke the shell as follows:
229
230
231              (void) strcpy(buffer, "echo -q");
232              (void) strcat(buffer, words);
233              if ((flags & WRDE_SHOWERR) == 0)
234                  (void) strcat(buffer, "2>/dev/null");
235              f = popen(buffer, "r");
236
237       The wordexp() function would read the resulting output, remove unquoted
238       backslashes,  and  break  into  words  at  unquoted  <blank>s.  If  the
239       WRDE_NOCMD  flag  was  set,  wordexp()  would have to scan words before
240       starting the subshell to make sure that there would be no command  sub‐
241       stitution.  In  any case, it would have to scan words for unquoted spe‐
242       cial characters.
243
244       Another proposal is to add the following options to sh:
245
246       -w wordlist
247
248              This option provides a wordlist expansion  service  to  applica‐
249              tions.   The words in wordlist shall be expanded and the follow‐
250              ing written to standard output:
251
252               1. The count of the number of words after expansion,  in  deci‐
253                  mal, followed by a null byte
254
255               2. The  number  of bytes needed to represent the expanded words
256                  (not including null separators), in decimal, followed  by  a
257                  null byte
258
259               3. The expanded words, each terminated by a null byte
260
261       If  an error is encountered during word expansion, sh exits with a non-
262       zero status after writing the former to report any  words  successfully
263       expanded
264
265       -P     Run  in  "protected"  mode.  If specified with the -w option, no
266              command substitution shall be performed.
267
268
269       With these options, wordexp() could be  implemented  fairly  simply  by
270       creating a subprocess using fork() and executing sh using the line:
271
272
273              execl(<shell path>, "sh", "-P", "-w", words, (char *)0);
274
275       after directing standard error to /dev/null.
276
277       It  seemed  objectionable  for  a  library routine to write messages to
278       standard error, unless explicitly requested, so wordexp()  is  required
279       to  redirect standard error to /dev/null to ensure that no messages are
280       generated, even for commands executed  for  command  substitution.  The
281       WRDE_SHOWERR  flag  can  be specified to request that error messages be
282       written.
283
284       The WRDE_REUSE flag allows the implementation to avoid the  expense  of
285       freeing  and reallocating memory, if that is possible. A minimal imple‐
286       mentation can call wordfree() when WRDE_REUSE is set.
287

FUTURE DIRECTIONS

289       None.
290

SEE ALSO

292       fnmatch()   ,   glob()   ,   the    Base    Definitions    volume    of
293       IEEE Std 1003.1-2001,  <wordexp.h>,  the  Shell and Utilities volume of
294       IEEE Std 1003.1-2001, Chapter 2, Shell Command Language
295
297       Portions of this text are reprinted and reproduced in  electronic  form
298       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
299       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
300       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
301       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
302       event of any discrepancy between this version and the original IEEE and
303       The Open Group Standard, the original IEEE and The Open Group  Standard
304       is  the  referee document. The original Standard can be obtained online
305       at http://www.opengroup.org/unix/online.html .
306
307
308
309IEEE/The Open Group                  2003                           WORDEXP(P)
Impressum