wordexp(3C)


wordexp, wordfree -- perform word expansions

Synopsis

   #include <wordexp.h>
   

int wordexp(const char *string, wordexp_t *pword, int flags);

void wordfree(wordexp_t *pword);

Description

These functions are part of the X/Open Portability Guide Issue 4 optional POSIX2 C-Language Binding feature group.

wordexp performs word expansions and places the list of expanded words into the structure pointed to by pword.

The first argument is a pointer to a string containing one or more words to be expanded. The expansions are the same as those performed by the shell if string are part of a command line representing the arguments to a utility. Therefore, string must not contain an unquoted newline or any of the unquoted shell special characters:

   |  & ; < >
except in the context of command substitution. It also must not contain unquoted parentheses or braces, except in the context of command or variable substitution. If string contains an unquoted comment character that is the beginning of a token, wordexp may treat the comment character as a regular character, or may interpret it as a comment indicator and ignore the remainder of string.

wordexp stores the number of generated words into a pointer to a list of pointers. Each individual field created during field splitting or pathname expansion is a separate word in the list. The first pointer after the last word pointer is a null pointer. The expansion of special parameters is unspecified.

You must allocate the storage pointed to by pword. wordexp allocates other space as needed, including memory pointed to by pword. wordfree frees any memory associated with pword from a previous call to wordexp.

flags controls the behavior of wordexp. The value of flags is the bitwise inclusive OR of zero or more of the following constants:


WRDE_APPEND
Append words generated to the ones from a previous call.

WRDE_DOOFFS
The value of the wrde_dooffs member pointed to by pword specifies how many null pointers to add to the beginning of pword.

WRDE_NOCMD
Fail if a command substitution is requested.

WRDE_REUSE
pword was passed to a previous successful call to wordexp, and has not been passed to wordfree. The result is the same as if wordfree had been called before wordexp without WRDE_REUSE.

WRDE_SHOWERR
Do not redirect stderr to /dev/null.

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

You can use WRDE_APPEND to append a new set of words to those generated by a previous call to wordexp. If two or more calls to wordexp are made with the same value of pword and without intervening calls to wordfree, the following rules apply:

  1. The first call must not set WRDE_APPEND. All following calls must set it.

  2. All calls must set WRDE_DOOFFS or none can set it.

  3. After the second, and each following call, pword will point to a list containing:

  4. The count returned in the wrde_dooffs member is the total number of words from all the calls.

The application can change any of the fields after a call to wordexp, but if it does it must reset them to the original value before later calls, using the same pword value, to wordfree or wordexp with the WRDE_APPEND or WRD_REUSE flag.

If string contains any of the following shell special characters:

   <newline> |  & ; < > ( ) { }
in an inappropriate context, wordexp will fail and the number of expanded words will be zero.

If WRDE_SHOWERR is set in flags, wordexp will redirect stderr to dev/null for any utilities executed as a result of command substitution while expanding words. wordexp may also write messages to stderr if syntax errors are detected.

If WRDE_DOOFFSS is set, pwordexp must have the same value for each wordexp call and wordfree call using a given pwordexp.

Return values

wordexp returns 0 if successful.

wordfree returns no value.

Errors

In the following conditions, wordexp returns and sets errno to:

WRDE_BADCHAR
One of the unquoted characters appears in words in an inappropriate context.

WRDE_BADVAL
Reference to an undefined shell variable when WRDE_UNDEF is set in flags.

WRDE_CMDSUB
Command substitution requested when WRDE_NOCMD was set in flags.

WRDE_NOSPACE
Attempt to allocate memory failed.

WRDE_SYNTAX
Shell syntax error.
If wordexp returns WRDE_NOSPACE, the structure is modified to indicate any successfully expanded words. In other cases there is no update.

References

fnmatch(3C), glob(3C), wordexp(5)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004