DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

wordexp(S-osr5)


wordexp, wordfree -- perform word expansions

Syntax

cc . . . -lc

#include <wordexp.h>

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

Description

wordexp(S-osr5) performs word expansion on one or more words contained in the string words, similar to that performed by the standard shell. One such example is to expand the (command substituting) string "`cat $HOME/filelist`" into the contents of the file filelist found in the user's $HOME directory.

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.

 +------------+-------------+-------------------------------------+
 |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.       |
 +------------+-------------+-------------------------------------+
wordexp( ) fills pwordexp->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-osr5) 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>:


WRDE_APPEND
Append words generated in this call to the list of words generated from previous calls to wordexp( ).

WRDE_DOOFFS
The number of null pointers to be inserted to the beginning of pwordexp->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.

WRDE_NOCMD
No command substitution is allowed. wordexp( ) will fail if command substitution is requested.

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.


WRDE_REUSE
Use pwordexp as freshly created. Make certain that pwordexp was passed to a previous successful call to wordexp( ), and has not been passed to wordfree( ). This flag has the same effect as passing pwordexp to wordfree( ) and then calling wordexp( ) using pwordexp, without WRDE_REUSE being set. Appending is not allowed if this flag is set.

WRDE_SHOWERR
Do not redirect stderr to /dev/null.

WRDE_UNDEF
Report error when an undefined shell variable is encountered.
To append a new set of words to those generated previously, make repeated calls to wordexp( ), with the same value of pwordexp and without any intervening calls to wordfree( ). The following rules apply when two or more calls to wordexp( ) are made to append words:

  1. The first call in sequence must not set WRDE_APPEND. All subsequent calls must have this flag set.

  2. Either all the calls set the WRDE_DOOFFS flag or none of the calls can set it.

  3. The list of pointers pointed by pwordexp->we_wordv contains the following after the second call:

  4. The number of words returned in pwordexp->we_wordc is updated to the total number of generated words from all previous calls, including the latest one.

  5. The application can change any of the fields in the pwordexp structure between calls to wordexp( ), or between calls to wordexp( ) and wordfree( ). However, when wordexp( ) is called the next time with the WRDE_APPEND flag set and using the same pwordexp value, or when wordfree( ) is called next time to free memories associated with pwordexp, those changed fields must be reset to their original values as immediately after wordexp( ) returned.
If the WRDE_DOOFFS flag is set, the value of pwordexp->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.

Return values

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].

Diagnostics

On systems which do not support the functionality, wordexp( ) sets errno to [ENOSYS] to indicate no support:


[ENOSYS]
Functionality not supported.
Otherwise, one of the following non-zero integers, defined in <wordexp.h>, may be returned by wordexp( ) to indicate an error:


WRDE_BADCHAR
One of the following special characters:
   <newline>  |  &  ;  <  >  (  )  {  }
is found in words in an inappropriate context and not quoted.

WRDE_BADVAL
Attempt to expand an undefined shell variable and the WRDE_UNDEF flag is set.

WRDE_CMDSUB
Command substitution requested but disallowed due to the setting of WRDE_NOCMD flag.

WRDE_NOSPACE
Cannot allocate more memory.

WRDE_SYNTAX
Some shell syntax error, such as unbalanced parentheses or unterminated string, was found in words.
If wordexp( ) fails due to WRDE_NOSPACE, it still updates pwordexp->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:


WRDE_NOSYS
/bin/posix/sh is not installed or does not support print -W.

WRDE_SYSERR
Some system error, mostly from the failure of fork(S-osr5), read(S-osr5), or pipe(S-osr5), occurred. errno may also be set in this case.

Notes

The word expansion performed by wordexp( ) is described in the ksh(C) manual page.

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.

Warning

The return values WRDE_NOSYS and WRDE_SYSERR from wordexp( ) are SCO OpenServer specific and may not be supported in future releases. To retain XPG4 compliance for an application code when it uses these return values, compile the code conditionally as in:
           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-osr5)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-osr5) and siginfo(FP) for further information.

Files


/bin/posix/sh
a link to /bin/ksh

See also

exec(S-osr5), fnmatch(S-osr5), glob(S-osr5), fork(S-osr5), ksh(C), sigaction(S-osr5), siginfo(FP)

Standards conformance

wordexp( ) and wordfree( ) are conformant with:
X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992.
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 -- 02 June 2005