WORDEXP(3)

NAME
wordexp - perform shell-style word expansions

LIBRARY
libc

SYNOPSIS
#include <wordexp.h>
int
wordexp(const char * restrict words, wordexp_t * restrict pwordexp, int flags);
void
wordfree(wordexp_t *pwordexp);

DESCRIPTION
The wordexp() function performs shell-style word expansion on words and places the list of expanded words into the structure pointed to by pwordexp.

The flags argument is the bitwise inclusive OR of any of the following constants:

WRDE_APPEND
    Append the words to those generated by a previous call to wordexp().

WRDE_DOOFFS
    As many NULL pointers as are specified by the we_offs member of we are added to the front of we_wordv.

WRDE_NOCMD
    Disallow command substitution in words. See the note in BUGS before using this.

WRDE_REUSE
    The we argument was passed to a previous successful call to wordexp() but has not been passed to wordfree(). The implementation may reuse the space allocated to it.

WRDE_SHOWERR
    Do not redirect shell error messages to /dev/null.

WRDE_UNDEF
    Report error on an attempt to expand an undefined shell variable.

The structure type wordexp_t includes the following members:

    size_t	we_wordc
    char	**we_wordv
    size_t	we_offs

The we_wordc member is the count of generated words.

The we_wordv member points to a list of pointers to expanded words.

The we_offs member is the number of slots to reserve at the beginning of the we_wordv member.

It is the caller's responsibility to allocate the storage pointed to by pwordexp. The wordexp() function allocates other space as needed, including memory pointed to by the we_wordv member.

The wordfree() function frees the memory allocated by wordexp().

IMPLEMENTATION NOTES
The wordexp() function is implemented as a wrapper around the undocumented wordexp shell built-in command.

RETURN VALUES
The wordexp() function returns zero if successful, otherwise it returns one of the following error codes:

WRDE_BADCHAR
    The words argument contains one of the following unquoted characters: <newline>, ‘|’, ‘&’, ‘’;, ‘<’, ‘>’, ‘(’, ‘’), ‘{’, ‘}’.

WRDE_BADVAL
    An attempt was made to expand an undefined shell variable and WRDE_UNDEF is set in flags.

WRDE_CMDSUB
    An attempt was made to use command substitution and WRDE_NOCMD is set in flags.

WRDE_NOSPACE
    Not enough memory to store the result.

WRDE_SYNTAX
    Shell syntax error in words.

WRDE_ERRNO
    An internal error occured and errno is set to indicate the error.

The wordfree() function returns no value.

ENVIRONMENT

IFS Field separator.

EXAMPLES
Invoke the editor on all.c files in the current directory and /etc/motd (error checking omitted):

    wordexp_t we;
    wordexp("${EDITOR:-vi} *.c /etc/motd", &we, 0);
    execvp(we->we_wordv[0], we->we_wordv);

DIAGNOSTICS
Diagnostic messages from the shell are written to the standard error output if WRDE_SHOWERR is set in flags.

SEE ALSO
sh(1), fnmatch(3), glob(3), popen(3), system(3)

STANDARDS
The wordexp() and wordfree() functions conform to p1003.1-2001. Their first release was in p1003.2-92. The return value WRDE_ERRNO is an extension.

BUGS
Do not pass untrusted user data to wordexp(), regardless of whether the WRDE_NOCMD flag is set. The wordexp() function attempts to detect input that would cause commands to be executed before passing it to the shell but it does not use the same parser so it may be fooled.