|
|
#include <wordexp.h>int wordexp(const char *words, wordexp_t *pwordexp, int flags); void wordfree(wordexp_t *pwordexp);
The structure of type wordexp_t pointed to by pwordexp is used by wordexp( ) to store the expansion results, and flags is used to modify the default behavior of wordexp( ).
The structure type wordexp_t is defined in the header file <wordexp.h> and includes at least the three members listed below:
| Member Type | Member Name | Description |
|---|---|---|
| size_t |
we_wordc
| Number of generated words. |
| char ** |
we_wordv
| Pointer to list of generated words. |
| size_t |
we_offs
| Number of pointers to reserve |
at the beginning of we_wordv.
|
->we_wordc
with the total number of generated words
and stores in pwordexp->we_wordv
a pointer to a list of pointers to all generated words.
The structure pointed to by pwordexp must be created first;
wordexp( )
then allocates other space as needed (like the memory pointed to by
we_wordv).
wordfree(S) frees all memory allocated for pwordexp from a previous call to wordexp( ), but does not free the pwordexp structure itself.
If words were command line arguments to a utility, shell would expand words into a list of individual words. wordexp( ) performs the same expansion on words as the shell would. If words contains any of the following special characters unquoted in an inappropriate context:
<newline> | & ; < > ( ) { }
wordexp( )
fails just as the shell would,
and the number of expanded words will be zero.
Except in the context of command substitution, newline or any of the following shell special characters must be quoted:
| & ; < >Except in the context of command or variable substitution, parentheses or braces must also be quoted. wordexp( ) interprets an unquoted comment character (# sign) at the beginning of a token in words as a comment indicator and ignores everything after the # sign in words.
Word expansion is a multi-stage process.
Before field splitting is done, tilde expansion, parameter expansion,
command substitution, and arithmetic expansion are performed.
After field splitting, if set -f (disable
filename expansion) is not in effect,
each field in the resulting list is expanded.
Within each expanded field, results are sorted according
to the effective collating sequence in the current locale.
Each individual field thus created during field splitting,
or pathname expansion (if performed), is a separate word
in the pwordexp->we_wordv list. The pointer immediately
after the last word pointer is a null pointer.
The special parameters are expanded in the same way as described in
``Parameter substitution''.
For details on field splitting and pathname expansion,
see ``Blank interpretation'' in
ksh(C);
for ordering of the
expanded words,
see ``File name generation'' in
ksh(C).
The behavior of wordexp( ) can be modified by flags, which is formed from a bitwise inclusive OR of zero or more of the following flags defined in <wordexp.h>:
->we_wordv is
pwordexp->we_offs.
In other words,
in the list of pointers pwordexp->we_wordv
pointed to,
the first pwordexp->we_offs pointers are null,
the next pwordexp->we_wordc pointers point
to the generated words,
and the final pointer is a null pointer again.
Use this flag if an application, for security purposes or for other reasons, does not want a user to execute shell commands. Some undesired side-effects, such as command execution or writing to a file, may also be prevented if unquoted shell special characters are not allowed.
->we_wordv
contains the following after the second call:
->we_offs null pointers if
WRDE_DOOFFS is set
->we_wordc
is updated to the
total number of generated
words from all previous calls, including the latest one.
->we_offs cannot be different for each
wordexp( )
and
wordfree( )
call when a given pwordexp is used.
As a result of command substitution while expanding words, error messages may be generated by the utilities executed (for example, when cat was given an illegal option in our example at the beginning). By default, these error messages are redirected to /dev/null by wordexp( ). If the WRDE_SHOWERR flag is set, stderr will not be redirected and wordexp( ) may write messages to stderr if there is any syntax error for the utility while expanding words.
wordfree( ) does not return any values.
wordexp( ) returns 0 on success and a non-zero integer for failure. See ``Diagnostics'' for specific integer values.
On systems which do not support the functionality, wordexp( ) returns WRDE_NOSYS and sets errno to [ENOSYS].
On systems which do not support the functionality, wordexp( ) sets errno to [ENOSYS] to indicate no support:
<newline> | & ; < > ( ) { }
is found in words in an inappropriate context and not quoted.
->we_wordc and
pwordexp->we_wordv
to record any words that were successfully expanded.
In other error situations, these two structure members
are not modified.
As SCO OpenServer specific features, wordexp( ) may also return the following two error return values:
Through wordexp( ), an application can obtain a word or words from a user and do all of the shell's expansion on the input. For example, when prompted for a list of filenames, a user can respond with anything that would be valid input in the shell and wordexp then expands the input string into a list of filenames.
switch (wordexp (words, pwordexp, flags)) {
case 0:
/* code for successful expansion */
break;
case WRDE_BADCHAR:
/* handle misuse of special characters in words */
break;
.
.
.
#ifdef WRDE_NOSYS
case WRDE_NOSYS:
/* handle errors due to /bin/ksh */
break;
#endif /* WRDE_NOSYS */
#ifdef WRDE_SYSERR
case WRDE_SYSERR:
/* handle errors due to other system errors */
break;
#endif /* WRDE_SYSERR */
.
.
.
}
The current implementation of wordexp( ) routine fork(S)s its child process to do word expansions. If the caller has SIGCHLD (or SIGCLD) signal handlers set up, these handlers will be triggered by the call on wordexp( ). See sigaction(S) and siginfo(FP) for further information.