Expands tokens from a stream of words.
#include <wordexp.h>
int wordexp (Words, Pwordexp, Flags) const char *Words; wordexp_t *Pwordexp; int Flags;
The wordexp subroutine performs word expansions equivalent to the word expansion that would be performed by the shell if the contents of the Words parameter were arguments on the command line. The list of expanded words are placed in the Pwordexp parameter. The expansions are the same as that which would be performed by the shell if the Words parameter were the part of a command line representing the parameters to a command. Therefore, the Words parameter cannot contain an unquoted <newline> character or any of the unquoted shell special characters | (pipe), & (ampersand), ; (semicolon), < (less than sign), or > (greater than sign), except in the case of command substitution. The Words parameter also cannot contain unquoted parentheses or braces, except in the case of command or variable substitution. If the Words parameter contains an unquoted comment character # (number sign) that is the beginning of a token, the wordexp subroutine may treat the comment character as a regular character, or may interpret it as a comment indicator and ignore the remainder of the expression in the Words parameter.
The wordexp subroutine allows an application to perform all of the shell's expansions on a word or words obtained from a user. For example, if the application prompts for a file name (or a list of file names) and then uses the wordexp subroutine to process the input, the user could respond with anything that would be valid as input to the shell.
The wordexp subroutine stores the number of generated words and a pointer to a list of pointers to words in the Pwordexp parameter. Each individual field created during the field splitting or path name expansion is a separate word in the list specified by the Pwordexp parameter. The first pointer after the last last token in the list is a null pointer. The expansion of special parameters * (asterisk), @ (at sign), # (number sign), ? (question mark), - (minus sign), $ (dollar sign), ! (exclamation point), and 0 is unspecified.
The words are expanded in the order shown below:
The value of the Flags parameter is the bitwise, inclusive OR of the constants below, which are defined in the wordexp.h file.
The WRDE_ APPEND flag can be used to append a new set of words to those generated by a previous call to the wordexp subroutine. The following rules apply when two or more calls to the wordexp subroutine are made with the same value of the Pwordexp parameter and without intervening calls to the wordfree subroutine:
The WRDE_NOCMD flag is provided for applications that, for security or other reasons, want to prevent a user from executing shell commands. Disallowing unquoted shell special characters also prevents unwanted side effects such as executing a command or writing to a file.
Unless the WRDE_SHOWERR flag is set in the Flags parameter, the wordexp subroutine redirects standard error to the /dev/null file for any utilities executed as a result of command substitution while expanding the Words parameter. If the WRDE_SHOWERR flag is set, the wordexp subroutine may write messages to standard error if syntax errors are detected while expanding the Words parameter.
The Pwordexp structure is allocated by the caller, but memory to contain the expanded tokens is allocated by the wordexp subroutine and added to the structure as needed.
The Words parameter cannot contain any <newline> characters, or any of the unquoted shell special characters | , & , ; , () , {} , < , or > , except in the context of command substitution.
If no errors are encountered while expanding the Words parameter, the wordexp subroutine returns a value of 0. If an error occurs, it returns a nonzero value indicating the error.
If the wordexp subroutine terminates due to an error, it returns one of the nonzero constants below, which are defined in the wordexp.h file.
If the wordexp subroutine returns the error value WRDE_SPACE, then the expression in the Pwordexp parameter is updated to reflect any words that were successfully expanded. In other cases, the Pwordexp parameter is not modified.
This subroutine is part of Base Operating System (BOS) Runtime.
The glob subroutine, wordfree subroutine.
For more information on basic and extended regular expressions, see Manipulating Strings with sed.