Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
WORDEXP(3)	       FreeBSD Library Functions Manual		    WORDEXP(3)

NAME
     wordexp --	perform	shell-style word expansions

LIBRARY
     Standard C	Library	(libc, -lc)

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 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_DOOFFS   As many NULL	pointers as are	specified by the we_offs mem-
		   ber 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 im-
		   plementation	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 using the undocumented
     freebsd_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 error after successful parsing, such as an attempt to
		   expand an undefined shell variable with WRDE_UNDEF 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 or an error during
		   fork(2).

     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 out-
     put 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
     The current wordexp() implementation does not recognize multibyte charac-
     ters other	than UTF-8, since the shell (which it invokes to perform ex-
     pansions) does not.

SECURITY CONSIDERATIONS
     Pathname generation may create output that	is exponentially larger	than
     the input size.

     Although this implementation detects command substitution reliably	for
     WRDE_NOCMD, the attack surface remains fairly large.  Also, some other
     implementations (such as older versions of	this one) may execute command
     substitutions even	if WRDE_NOCMD is set.

FreeBSD	13.0		      September	30, 2015		  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | IMPLEMENTATION NOTES | RETURN VALUES | ENVIRONMENT | EXAMPLES | DIAGNOSTICS | SEE ALSO | STANDARDS | BUGS | SECURITY CONSIDERATIONS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=wordexp&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help