# wordexp

## NAME



           wordexp, wordfree - perform word expansion like a posix-shell
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <wordexp.h>**
    
           **int wordexp(const char *restrict** _s_**, wordexp_t *restrict** _p_**, int** _flags_**);**
           **void wordfree(wordexp_t ***_p_**);**
    
       Feature Test Macro Requirements for glibc (see
       feature_test_macros(7)):
    
           **wordexp**(), **wordfree**():
               _XOPEN_SOURCE
    


## DESCRIPTION



           The function **wordexp**() performs a shell-like expansion of the
           string _s_ and returns the result in the structure pointed to by _p_.
           The data type _wordexp_t_ is a structure that at least has the
           fields _we_wordc_ , _we_wordv_ , and _we_offs_.  The field _we_wordc_ is a
           _size_t_ that gives the number of words in the expansion of _s_.  The
           field _we_wordv_ is a _char **_ that points to the array of words
           found.  The field _we_offs_ of type _size_t_ is sometimes (depending
           on _flags_ , see below) used to indicate the number of initial
           elements in the _we_wordv_ array that should be filled with NULLs.
    
           The function **wordfree**() frees the allocated memory again.  More
           precisely, it does not free its argument, but it frees the array
           _we_wordv_ and the strings that points to.
    
       **The string argument**
           Since the expansion is the same as the expansion by the shell (see
           **sh**(1)) of the parameters to a command, the string _s_ must not
           contain characters that would be illegal in shell command
           parameters.  In particular, there must not be any unescaped
           newline or |, &, ;, <, >, (, ), {, } characters outside a command
           substitution or parameter substitution context.
    
           If the argument _s_ contains a word that starts with an unquoted
           comment character #, then it is unspecified whether that word and
           all following words are ignored, or the # is treated as a non-
           comment character.
    
       **The expansion**
           The expansion done consists of the following stages: tilde
           expansion (replacing ~user by user's home directory), variable
           substitution (replacing $FOO by the value of the environment
           variable FOO), command substitution (replacing $(command) or
           `command` by the output of command), arithmetic expansion, field
           splitting, wildcard expansion, quote removal.
    
           The result of expansion of special parameters ($@, $*, $#, $?, $-,
           $$, $!, $0) is unspecified.
    
           Field splitting is done using the environment variable $IFS.  If
           it is not set, the field separators are space, tab, and newline.
    
       **The output array**
           The array _we_wordv_ contains the words found, followed by a NULL.
    
       **The flags argument**
           The _flag_ argument is a bitwise inclusive OR of the following
           values:
    
           **WRDE_APPEND**
                  Append the words found to the array resulting from a
                  previous call.
    
           **WRDE_DOOFFS**
                  Insert _we_offs_ initial NULLs in the array _we_wordv_.  (These
                  are not counted in the returned _we_wordc_.)
    
           **WRDE_NOCMD**
                  Don't do command substitution.
    
           **WRDE_REUSE**
                  The argument _p_ resulted from a previous call to **wordexp**(),
                  and **wordfree**() was not called.  Reuse the allocated
                  storage.
    
           **WRDE_SHOWERR**
                  Normally during command substitution _stderr_ is redirected
                  to _/dev/null_.  This flag specifies that _stderr_ is not to be
                  redirected.
    
           **WRDE_UNDEF**
                  Consider it an error if an undefined shell variable is
                  expanded.
    


## RETURN VALUE



           On success, **wordexp**() returns 0.  On failure, **wordexp**() returns
           one of the following nonzero values:
    
           **WRDE_BADCHAR**
                  Illegal occurrence of newline or one of |, &, ;, <, >, (,
                  ), {, }.
    
           **WRDE_BADVAL**
                  An undefined shell variable was referenced, and the
                  **WRDE_UNDEF** flag told us to consider this an error.
    
           **WRDE_CMDSUB**
                  Command substitution requested, but the **WRDE_NOCMD** flag
                  told us to consider this an error.
    
           **WRDE_NOSPACE**
                  Out of memory.
    
           **WRDE_SYNTAX**
                  Shell syntax error, such as unbalanced parentheses or
                  unmatched quotes.
    


## ATTRIBUTES



           For an explanation of the terms used in this section, see
           attributes(7).
           ┌────────────┬───────────────┬───────────────────────────────────┐
           │ **Interface** │ **Attribute** │ **Value** │
           ├────────────┼───────────────┼───────────────────────────────────┤
           │ **wordexp**()  │ Thread safety │ MT-Unsafe race:utent const:env    │
           │            │               │ env sig:ALRM timer locale         │
           ├────────────┼───────────────┼───────────────────────────────────┤
           │ **wordfree**() │ Thread safety │ MT-Safe                           │
           └────────────┴───────────────┴───────────────────────────────────┘
    
           In the above table, _utent_ in _race:utent_ signifies that if any of
           the functions setutent(3), getutent(3), or endutent(3) are used in
           parallel in different threads of a program, then data races could
           occur.  **wordexp**() calls those functions, so we use race:utent to
           remind users.
    


## STANDARDS



           POSIX.1-2008.
    


## EXAMPLES



           The output of the following example program is approximately that
           of "ls [a-c]*.c".
    
           #include <stdio.h>
           #include <stdlib.h>
           #include <wordexp.h>
    
           int
           main(void)
           {
               wordexp_t p;
               char **w;
    
               wordexp("[a-c]*.c", &p, 0);
               w = p.we_wordv;
               for (size_t i = 0; i < p.we_wordc; i++)
                   printf("%s\n", w[i]);
               wordfree(&p);
               exit(EXIT_SUCCESS);
           }
    


* * *