wordexp

Expand special constructions.

Syntax

   #include <wordexp.h>

   int wordexp (const char *words, wordexp_t *expansions, int flags);

Parameters

words

is a string containing various special constructions that are typically expanded in shell command lines (for example, command substitutions, directory substitutions, parameter expansions, and so on).

expansions

points to an object of type wordexp_t where wordexp() can store the expanded version of words. It is created by the caller.

flags

is a collection of flags controlling the wordexp() action. Flags are specified by ORing together symbolic constants defined in <wordexp.h>. Possible symbols are:

WRDE_APPEND: appends expansions to an existing expansions list generated by a previous call to wordexp().
WRDE_DOOFFS: uses the we_offs field in the wordexp_t structure expansions.
WRDE_NOCMD: does not perform command substitution. wordexp() fails if command substitution is attempted.
WRDE_REUSE: expansions was passed to previous successful call to wordexp() and has not been passed to wordfree(). The result is the same as if the application had called wordfree() and then called wordexp().
WRDE_SHOWERR: Do not redirect the standard error to /dev/null.
WRDE_UNDEF: Reports error on attempt to expand an undefined shell variable.

Return Values

If wordexp() completes successfully, it returns zero. Otherwise, it returns one of the following error messages.

Description

wordexp() expands special constructs in the string words. See the section Expanded Constructs for a list of the constructs that wordexp() expands.

wordexp() returns the expansion using a wordexp_t structure. This structure has the following fields:

int we_wordc;: is the number of words in the expansion of words. This field is set by wordexp().
char **we_wordv;: points to a list of strings giving the expansions of words from words. Each individual field created during expansion becomes a separate word in the we_wordv list. The first pointer after the last path name is NULL. This field is set by wordexp().
int we_offs;: tells how many NULL pointers you want at the beginning of the we_wordv list. This creates a specified amount of `blank' space at the beginning of we_wordv that can be used for other purposes. For example, you might fill this space with other arguments before passing the whole we_wordv vector as an argument to a function like execv().

You set we_offs before calling wordexp(). wordexp() puts the specified number of NULL pointers at the beginning of the we_wordv list before putting in pointers to the strings giving the expansion of words. wordexp() only pays attention to we_offs if WRDE_DOOFFS is set in flags.

If WRDE_APPEND is specified, wordexp() follows these rules:

If WRDE_DOOFFS is set in the first call to wordexp(), it must be set in subsequent calls and we_offs must have the same value in each call.
If WRDE_DOOFFS is not set in the first call, it must not be set in subsequent calls.
After the second call, we_wordv points to a list containing: the number of NULL pointers as determined by WRDE_DOOFFS and we_offs; pointers to the words that were in the list before the second call, in the same order as before; and pointers to the new words obtained by the second call, in the order dictated by the flags for the second call.
we_wordc gives the total number of words from all the calls.

You must not change we_wordc or we_wordv between calls to wordexp().

Expanded Constructs

wordexp() performs the following expansions in the order given:

Directory Substitution

expands constructs of the form ~logname into the full path name of the user logname's home directory.

Parameter Expansion

expands the following constructs:

${parameter}
${parameter:-word}
${parameter:=word}
${parameter:?word}
${parameter:+word}
${#parameter}
${parameterword}
${parameterword}
${parameter#word}
${parameter##word}

The result of the expansion of these constructs is detailed in the sh(1) man page.

Command Substitution

expands the following constructs

$(command)
`command`

by executing command and replacing the construct with its output.

Arithmetic Expansion

expands constructs of the form

$((expression))

by replacing the construct with the value of the arithmetic expression.

These expansions are discussed in much greater detail in sh(1).

After performing the various expansions, wordexp() breaks up the result into separate words. Words are assumed to be separated by any one of the characters in the string value of the environment variable IFS. If IFS does not exist, wordexp() assumes that words are separated by one or more white space characters (blanks, tabs, or newlines). When splitting words in this way, wordexp()

After breaking up words into these separate words, wordexp() performs filename generation on names that are not quoted (see sh(1)).

Finally, wordexp() removes backslashes, quotes, and apostrophes from expanded strings, as appropriate.




	NOTE: `wordexp()` does not handle the special meanings of `\|` (pipe), `&` (put job in background), `;` (separate one command from another), `<` (input redirection) or `>` (output redirection). If the words string contains any of these outside of quotes or apostrophes, `wordexp()` fails and does not expand any words.

Once a program has finished using the paths structure, it should use wordfree() to free up the space used to store the path name list.

Errors

If an error occurs, errno is set to one of the following values:

`WRDE_BADCHAR`	CAUSE	An unquoted shell metacharacter appeared in words in an inappropriate context.
	ACTION	Examine and correct the syntax of the words string that was passed to the function.
`WRDE_BADVAL`	CAUSE	You attempted to reference an undefined shell variable when `WRDE_UNDEF` was set in `flags`.
	ACTION	Unset `WRDE_UNDEF`, or do not use undefined shell variables.
`WRDE_CMDSUB`	CAUSE	Command substitution was requested when `WRDE_NOCMD` was set in `flags`.
	ACTION	Unset `WRDE_NOCMD`, or do not request command substitution.
`WRDE_ERRNO`	CAUSE	A system call failed inside `wrdexp()`, setting the variable errno. The failure was one of the following: `confstr()` failed to get the name of the shell `pipe()` was unable to create a pipe `wordexp()` was unable to `fork()` or `exec()` the shell. `waitpid()` for a child process failed.
	ACTION	Check the value of the variable `errno` to determine the true cause of the error.
`WRDE_NOSPACE`	CAUSE	`wordexp()` was unable to allocate memory for one of its operations. `we_wordc` and `we_wordv` are still updated to show whatever words have already expanded.
	ACTION	Free up more memory.
`WRDE_SYNTAX`	CAUSE	words contained a shell syntax error, such as an unbalanced parentheses or unterminated string.
	ACTION	Correct the syntax of words.

wordexp

Technical documentation

» Table of Contents

» Index