wordexp(), wordfree()

perform word expansions 

Function


SYNOPSIS

#include <wordexp.h>

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

void wordfree(wordexp_t *pwordexp);


DESCRIPTION

The wordexp() performs word expansions subject to standard shell quoting and places the list of expanded words in the structure pointed to by pwordexp.

The expansion of words is the same as that performed by sh if words were arguments to a utility on a sh command line.

words cannot contain an unquoted newline or any of the following special characters:

|   &   ;   <   > 

except in the context of command substitution. words may also not contain unquoted parentheses or braces, except in the context of command or variable substitution. If words contains an unquoted comment character (#) that begins a token, wordexp() may treat treat it as a regular character or as a comment indicator. If it is treated as a comment character, wordexp() ignores the remainder of words.

The wordexp() function stores the number of generated words in the we_wordc member of pwordexp and a pointer to a list of pointers to words in the we_wordv member.

The caller must allocate the storage pointed to by pwordexp; however, wordexp() allocates other memory as needed, including that pointed to by the we_wordv member of pwordexp.

The flags argument controls the behavior of wordexp(). Its value is the bitwise-OR of one or more of the following flags:

WRDE_APPEND 

Appends words to those generated by previous wordexp() calls with the same pwordexp argument.

WRDE_DOOFFS 

Use the we_offs member of pwordexp to specify the number of null pointers to add to the beginning of the we_wordv member of pwordexp. In other words, the we_wordv member points to we_offs null pointers, followed by wordc word pointers, followed by a null pointer.

WRDE_NOCMD 

Fail if command substitution is requested.

WRDE_REUSE 

The pwordexp argument was passed to a previous successful wordexp() call, and has not been passed to wordfree(). The result is the same as if the application called wordfree() followed by wordexp() without WRDE_REUSE.

WRDE_SHOWERR 

Do not redirect the standard error stream. Normally, wordexp() redirects any output on the standard error stream generated when executing utilities during command substitution to /dev/null.

WRDE_UNDEF 

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

The wordfree() function frees all memory associated with pwordexp from a previous call to wordexp().


PARAMETERS

flags 

Contains a bitwise-OR value that controls the behavior of wordexp().

pwordexp 

Points to a wordexp_t structure that contains the expanded words.

words 

Points to the string on which word expansion is to be performed.


RETURN VALUES

The wordfree() function does not return a value.

On success, wordexp() returns 0. On failure, it returns an error values. If the returned error value is WRDE_NOSPACE, the we_wordc and we_wordv members of pwordexp reflect the words that were successfully expanded. For all other error values, pwordexp is unchanged. Possible error values are:

WRDE_BADCHAR 

An unquoted metacharacter appeared in the wrong place.

WRDE_BADVAL 

There was an undefined environment variable reference with the WRDE_UNDEF flag set.

WRDE_CMDSUB 

Command substitution was requested with the WRDE_NOCMD flag set.

WRDE_NOSPACE 

The process ran out of memory.

WRDE_SYNTAX 

There was a sh syntax error.


CONFORMANCE

POSIX.2


MULTITHREAD SAFETY LEVEL

Unsafe.


PORTING ISSUES

None.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Commands:
sh


PTC MKS Toolkit 10.3 Documentation Build 39.