WORDEXP(3)

WORDEXP(3) | Library Functions Manual | WORDEXP(3)

# NAME

`wordexp` —
perform shell-style word expansions

# LIBRARY

Standard C Library (libc, -lc)

# 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 occurred 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 IEEE Std 1003.1-2001 (“POSIX.1”). Their first release was in IEEE Std 1003.2-1992 (“POSIX.2”). 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.

July 13, 2004 | NetBSD 10.0