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

NAME

12       wordexp, wordfree — perform word expansions
13

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

190       No errors are defined.
191
192       The following sections are informative.
193

EXAMPLES

195       None.
196

APPLICATION USAGE

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

RATIONALE

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

FUTURE DIRECTIONS

303       None.
304

SEE ALSO

306       exec, fnmatch(), glob()
307
308       The Base Definitions volume of POSIX.1‐2017, <wordexp.h>
309
310       The  Shell  and Utilities volume of POSIX.1‐2017, Chapter 2, Shell Com‐
311       mand Language
312
314       Portions of this text are reprinted and reproduced in  electronic  form
315       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
316       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
317       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
318       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
319       event of any discrepancy between this version and the original IEEE and
320       The Open Group Standard, the original IEEE and The Open Group  Standard
321       is  the  referee document. The original Standard can be obtained online
322       at http://www.opengroup.org/unix/online.html .
323
324       Any typographical or formatting errors that appear  in  this  page  are
325       most likely to have been introduced during the conversion of the source
326       files to man page format. To report such errors,  see  https://www.ker
327       nel.org/doc/man-pages/reporting_bugs.html .
328
329
330
331IEEE/The Open Group                  2017                          WORDEXP(3P)
Impressum