wordexp(3C) wordexp(3C)
NAME
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:
Copyright 1994 Novell, Inc. Page 1
wordexp(3C) wordexp(3C)
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:
Zero or more null pointers as specified by wrde_dooffs
and WRDE_DOOFFS.
Pointers to the words that were in the pword list before
the call, in the same order as before
Copyright 1994 Novell, Inc. Page 2
wordexp(3C) wordexp(3C)
Pointers to the new words generated by the latest call,
in specified order.
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 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 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 WRDE_NOSYS and sets errno to ENOSYS.
wordfree returns and sets errno to ENOSYS.
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.
Copyright 1994 Novell, Inc. Page 3
wordexp(3C) wordexp(3C)
WRDE_NOSPACE
Attempt to allocate memory failed.
WRDE_SYNTAX
Shell syntax error.
REFERENCES
fnmatch(3C), glob(3C), wordexp(5)
Copyright 1994 Novell, Inc. Page 4