wordexp(3C) DG/UX R4.11MU05 wordexp(3C)
NAME
wordexp, wordfree - perform word expansions
SYNOPSIS
#include <wordexp.h>
int wordexp(const char *string, wordexpt *pword,int flags);
void wordfree(wordexpt *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:
WRDEAPPEND
Append words generated to the ones from a previous call.
WRDEDOOFFS
The value of the wrdedooffs member pointed to by pword
specifies how many null pointers to add to the beginning of
pword.
WRDENOCMD
Fail if a command substitution is requested.
WRDEREUSE
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
WRDEREUSE.
WRDESHOWERR
Do not redirect stderr to /dev/null.
WRDEUNDEF
Report error on an attempt to expand an undefined shell
variable.
You can use WRDEAPPEND 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 WRDEAPPEND. All following calls
must set it.
2 All calls must set WRDEDOOFFS or none can set it.
3 After the second, and each following call, pword will point to
a list containing:
Zero or more null pointers as specified by wrdedooffs and
WRDEDOOFFS.
Pointers to the words that were in the pword list before the
call, in the same order as before
Pointers to the new words generated by the latest call, in
specified order.
4 The count returned in the wrdedooffs 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
WRDEAPPEND or WRDREUSE flag.
If string contains an unquoted newline or any of the following shell
special characters:
| & ; < > ( ) { }
in an inappropriate context, wordexp will fail and the number of
expanded words will be zero.
If WRDESHOWERR 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 WRDEDOOFFSS is set, pwordexp must have the same value for each
wordexp call and wordfree call using a given pwordexp.
Return Values
wordexp returns WRDENOSYS and sets errno to ENOSYS.
wordfree returns and sets errno to ENOSYS.
Errors
In the following conditions, wordexp returns and sets errno to:
WRDEBADCHAR
One of the unquoted characters appears in words in an
inappropriate context.
WRDEBADVAL
Reference to an undefined shell variable when WRDEUNDEF is
set in flags.
WRDECMDSUB
Command substitution requested when WRDENOCMD was set in
flags.
WRDENOSPACE
Attempt to allocate memory failed.
WRDESYNTAX
Shell syntax error.
REFERENCES
fnmatch(3C), glob(3C)
Licensed material--property of copyright holder(s)