WORDEXP(3)

NAME
wordexp - perform shell-style word expansions

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. It places the list of words into the we_wordv member of pwordexp and the number of words into we_wordc.

The flags argument (see BUGS) 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_DOOFS
    As many NULL pointers as are specified by the we_offs member of pwordexp 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 pwordexp 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 wordexp_t structure is defined in <wordexp.h> as:

    typedef struct {
    	size_t	we_wordc;	/* count of words matched */
    	char	**we_wordv;	/* pointer to list of words */
    	size_t	we_offs;	/* slots to reserve in we_wordv */
    } wordexp_t;

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

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.

The wordfree() function returns no value.

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

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

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

BUGS
This version of wordexp() ignores the value of the flags argument.

COPYRIGHT
Copyright 1995-2002 University Corporation for Atmospheric Research/Unidata

Portions of this software were developed by the Unidata Program at the University Corporation for Atmospheric Research.