Ubuntu Manpage: wordexp, wordfree - perform word expansion like a posix-shell

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.

HISTORY

       POSIX.1-2001.  glibc 2.1.

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);
       }