NAME    [Toc]    [Back]

     wordexp -- perform shell-style word expansions

LIBRARY    [Toc]    [Back]

     Standard C Library (libc, -lc)

SYNOPSIS    [Toc]    [Back]

     #include <wordexp.h>

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

     void
     wordfree(wordexp_t *we);

DESCRIPTION    [Toc]    [Back]

     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 number
     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_DOOFS    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
		   implementation 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    [Toc]    [Back]

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

RETURN VALUES    [Toc]    [Back]

     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    [Toc]    [Back]

     IFS  Field separator.

EXAMPLES    [Toc]    [Back]

     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    [Toc]    [Back]

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

SEE ALSO    [Toc]    [Back]

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

STANDARDS    [Toc]    [Back]

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

BUGS    [Toc]    [Back]

     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.


FreeBSD 5.2.1		       December 27, 2002		 FreeBSD 5.2.1