1WORDEXP(3P)                POSIX Programmer's Manual               WORDEXP(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       wordexp, wordfree — perform word expansions
14

SYNOPSIS

16       #include <wordexp.h>
17
18       int wordexp(const char *restrict words, wordexp_t *restrict pwordexp,
19           int flags);
20       void wordfree(wordexp_t *pwordexp);
21

DESCRIPTION

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

RETURN VALUE

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

ERRORS

186       No errors are defined.
187
188       The following sections are informative.
189

EXAMPLES

191       None.
192

APPLICATION USAGE

194       The wordexp() function is intended to be used by  an  application  that
195       wants  to  do all of the shell's expansions on a word or words obtained
196       from a user. For example, if the application prompts for a pathname (or
197       list  of  pathnames)  and then uses wordexp() to process the input, the
198       user could respond with anything that would be valid as  input  to  the
199       shell.
200
201       The  WRDE_NOCMD flag is provided for applications that, for security or
202       other reasons, want to prevent a user from  executing  shell  commands.
203       Disallowing  unquoted  shell  special characters also prevents unwanted
204       side-effects, such as executing a command or writing a file.
205
206       POSIX.1‐2008 does not require the wordexp() function to be  thread-safe
207       if  passed  an expression referencing an environment variable while any
208       other thread is concurrently modifying any  environment  variable;  see
209       exec.
210
211       Even  though  the  WRDE_SHOWERR flag allows the implementation to write
212       messages to stderr during command substitution or syntax  errors,  this
213       standard  does  not provide any way to detect write failures during the
214       output of such messages.
215

RATIONALE

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

FUTURE DIRECTIONS

293       None.
294

SEE ALSO

296       exec, fnmatch(), glob()
297
298       The Base Definitions volume of POSIX.1‐2008, <wordexp.h>
299
300       The Shell and Utilities volume of POSIX.1‐2008, Chapter 2,  Shell  Com‐
301       mand Language
302
304       Portions  of  this text are reprinted and reproduced in electronic form
305       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
306       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
307       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
308       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
309       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
310       event of any discrepancy between this version and the original IEEE and
311       The Open Group Standard, the original IEEE and The Open Group  Standard
312       is  the  referee document. The original Standard can be obtained online
313       at http://www.unix.org/online.html .
314
315       Any typographical or formatting errors that appear  in  this  page  are
316       most likely to have been introduced during the conversion of the source
317       files to man page format. To report such errors,  see  https://www.ker
318       nel.org/doc/man-pages/reporting_bugs.html .
319
320
321
322IEEE/The Open Group                  2013                          WORDEXP(3P)
Impressum