wordexp(3head) [sunos man page]

wordexp.h(3HEAD)						      Headers							  wordexp.h(3HEAD)

NAME

       wordexp.h, wordexp - word-expansion types

SYNOPSIS

       #include <wordexp.h>

DESCRIPTION

       The <wordexp.h> header defines the structures and symbolic constants used by the wordexp() and wordfree() functions. See wordexp(3C).

       The structure type wordexp_t contains the following members:

       size_t we_wordc	      /* count of words matched by words */
       char   **we_wordv      /* pointer to list of expanded words */
       size_t we_offs	      /* slots to reserve at the beginning of we_wordv

       The flags argument to the wordexp() function is the bitwise-inclusive OR of the following flags:

       WRDE_APPEND     Append words to those previously generated.

       WRDE_DOOFFS     Number of null pointers to prepend to we_wordv.

       WRDE_NOCMD      Fail if command substitution is requested.

       WRDE_REUSE      The  pwordexp  argument	was  passed to a previous successful call to wordexp(), and has not been passed to wordfree(). The
		       result is the same as if the application had called wordfree() and then called 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.

       The following constants are defined as error return values:

       WRDE_BADCHAR    One of the unquoted characters--<newline>, '|', '&', ';', '<', '>', '(', ')', '{', '}'--appears in words in an  inappropri-
		       ate context.

       WRDE_BADVAL     Reference to 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_NOSYS      Reserved.

       WRDE_SYNTAX     Shell syntax error, such as unbalanced parentheses or unterminated string.

       The <wordexp.h> header defines the following type:

       size_t	       As described in <stddef.h>.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       wordexp(3C), attributes(5), standards(5)

SunOS 5.10							    10 Sep 2004 						  wordexp.h(3HEAD)

WORDEXP(3)						   BSD Library Functions Manual 						WORDEXP(3)

NAME

     wordexp -- perform shell-style word expansions

SYNOPSIS

     #include <wordexp.h>

     int
     wordexp(const char * restrict words, wordexp_t * restrict we, int flags);

     void
     wordfree(wordexp_t *we);

DESCRIPTION

     The wordexp() function performs shell-style word expansion on words and places the list of words into the we_wordv member of we, and the num-
     ber of words into we_wordc.

     The flags argument is the bitwise inclusive OR of any of the following constants:

     WRDE_APPEND   Append the words to those generated by a previous call to wordexp().

     WRDE_DOOFFS   As many NULL pointers as are specified by the we_offs member of we are added to the front of we_wordv.

     WRDE_NOCMD    Disallow command substitution in words.  See the note in BUGS before using this.

     WRDE_REUSE    The we argument was passed to a previous successful call to wordexp() but has not been passed to wordfree().  The implementa-
		   tion may reuse the space allocated to it.

     WRDE_SHOWERR  Do not redirect shell error messages to /dev/null.

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

     The wordexp_t structure is defined in <wordexp.h> as:

	   typedef struct {
		   size_t  we_wordc;	   /* count of words matched */
		   char    **we_wordv;	   /* pointer to list of words */
		   size_t  we_offs;	   /* slots to reserve in we_wordv */
	   } wordexp_t;

     The wordfree() function frees the memory allocated by wordexp().

IMPLEMENTATION NOTES

     The wordexp() function is implemented as a wrapper around the undocumented wordexp shell built-in command.

RETURN VALUES

     The wordexp() function returns zero if successful, otherwise it returns one of the following error codes:

     WRDE_BADCHAR  The words argument contains one of the following unquoted characters: <newline>, '|', '&', ';', '<', '>', '(', ')', '{', '}'.

     WRDE_BADVAL   An attempt was made to expand an undefined shell variable and WRDE_UNDEF is set in flags.

     WRDE_CMDSUB   An attempt was made to use command substitution and WRDE_NOCMD is set in flags.

     WRDE_NOSPACE  Not enough memory to store the result.

     WRDE_SYNTAX   Shell syntax error in words.

     The wordfree() function returns no value.

ENVIRONMENT

     IFS  Field separator.

EXAMPLES

     Invoke the editor on all .c files in the current directory and /etc/motd (error checking omitted):

	   wordexp_t we;

	   wordexp("${EDITOR:-vi} *.c /etc/motd", &we, 0);
	   execvp(we.we_wordv[0], we.we_wordv);

DIAGNOSTICS

     Diagnostic messages from the shell are written to the standard error output if WRDE_SHOWERR is set in flags.

SEE ALSO

     sh(1), fnmatch(3), glob(3), popen(3), system(3)

STANDARDS

     The wordexp() and wordfree() functions conform to IEEE Std 1003.1-2001 (``POSIX.1'').

BUGS

     Do not pass untrusted user data to wordexp(), regardless of whether the WRDE_NOCMD flag is set.  The wordexp() function attempts to detect
     input that would cause commands to be executed before passing it to the shell but it does not use the same parser so it may be fooled.

     The current wordexp() implementation does not recognize multibyte characters, since the shell (which it invokes to perform expansions) does
     not.

BSD
								   July 29, 2004							       BSD