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

FreeBSD Manual Pages


home | help
wordexp(3C)		 Standard C Library Functions		   wordexp(3C)

       wordexp,	wordfree - perform word	expansions

       #include	<wordexp.h>

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

       void wordfree(wordexp_t *pwordexp);

       The  wordexp()  function	 performs word expansions, subject to quoting,
       and places the list of expanded words into the structure	pointed	to  by

       The wordfree() function frees any memory	allocated by wordexp() associ-
       ated with pwordexp.

   words Argument
       The words argument is a pointer to a  string  containing	 one  or  more
       words  to be expanded. The expansions will be the same as would be per-
       formed by the shell if words were the part of a command line represent-
       ing  the	 arguments  to a utility. Therefore, words must	not contain an
       unquoted	NEWLINE	or any of the unquoted shell special characters:

	       |   &   ;   <   >

       except in the context of	command	substitution. It also must not contain
       unquoted	 parentheses  or  braces,  except in the context of command or
       variable	substitution. If the argument words contains an	unquoted  com-
       ment  character	(number	 sign) that is the beginning of	a token, word-
       exp() may treat the comment character as	a regular  character,  or  may
       interpret it as a comment indicator and ignore the remainder of words.

   pwordexp Argument
       The  structure  type wordexp_t is defined in the	header <wordexp.h> and
       includes	at least 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 pwordexp-_we_wordv.

       The wordexp() function stores the number	of generated words into	pword-
       exp-_we_wordc  and  a  pointer to a list	of pointers to words in	pword-
       exp-_we_wordv. Each individual field created during field splitting  is
       a  separate  word in the	pwordexp-_we_wordv list.  The words are	in or-
       der. The	first pointer after the	last  word  pointer  will  be  a  null

       It is the caller's responsibility to allocate the storage pointed to by
       pwordexp. The wordexp() function	allocates other	space as  needed,  in-
       cluding	memory	pointed	to by pwordexp-_we_wordv. The wordfree() func-
       tion frees any memory associated	with pwordexp from a previous call  to

   flags Argument
       The  flags  argument  is	used to	control	the behavior of	wordexp(). The
       value of	flags is the bitwise inclusive OR of zero or more of the  fol-
       lowing constants, which are defined in <wordexp.h>:

	     Append  words generated to	the ones from a	previous call to word-

	     Make use of  pwordexp-_we_offs.  If  this	flag  is  set,	pword-
	     exp-_we_offs  is used to specify how many NULL pointers to	add to
	     the beginning  of	pwordexp-_we_wordv.  In	 other	words,	pword-
	     exp-_we_wordv will	point to pwordexp-_we_offs NULL	pointers, fol-
	     lowed by pwordexp-_we_wordc word pointers,	 followed  by  a  NULL

	     Fail if command substitution is requested.

	     The pwordexp argument was passed to a previous successful call to
	     wordexp(),	and has	not been passed	to wordfree(). The result will
	     be	 the same as if	the application	had called wordfree() and then
	     called wordexp() without WRDE_REUSE.

	     Do	not redirect stderr to /dev/null.

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

       The WRDE_APPEND flag can	be used	to append a new	set of words to	 those
       generated  by  a	 previous call to wordexp(). The following rules apply
       when two	or more	calls to wordexp() are made with  the  same  value  of
       pwordexp	and without intervening	calls to wordfree():

       1. The  first  such call	must not set WRDE_APPEND. All subsequent calls
	  must set it.

       2. All of the calls must	set WRDE_DOOFFS, or all	must not set it.

       3. After	the second and each subsequent call,  pwordexp-_we_wordv  will
	  point	to a list containing the following:

	  a. zero  or  more  NULL  pointers,  as  specified by WRDE_DOOFFS and

	  b. pointers to the words that	were in	 the  pwordexp-_we_wordv  list
	     before the	call, in the same order	as before.

	  c. pointers  to  the	new words generated by the latest call,	in the
	     specified order.

       4. The count returned in	pwordexp-_we_wordc will	be the total number of
	  words	from all of the	calls.

       5. The  application  can	change any of the fields after a call to word-
	  exp(), but if	it does	it must	reset them to the original  value  be-
	  fore a subsequent call, using	the same pwordexp value, to wordfree()
	  or wordexp() with the	WRDE_APPEND or WRDE_REUSE flag.

       If words	contains an unquoted:

	      NEWLINE |	  &   ;	  <   >	  (   )	  {   }

       in an inappropriate context, wordexp() will fail, and the number	of ex-
       panded words will be zero.

       Unless  WRDE_SHOWERR is set in flags, wordexp() will redirect stderr to
       /dev/null for any utilities executed as a result	of  command  substitu-
       tion while expanding words.

       If  WRDE_SHOWERR	is set,	wordexp() may write messages to	stderr if syn-
       tax errors are detected while expanding words. If WRDE_DOOFFS  is  set,
       then  pwordexp-_	 we_offs  must	have the same value for	each wordexp()
       call and	wordfree() call	using a	given pwordexp.

       The following constants are defined as error return values:

	     One of the	unquoted characters:

	     NEWLINE |	 &   ;	 <   >	 (   )	 {   }

       appears in words	in an inappropriate context.

	     Reference to undefined shell variable when	WRDE_UNDEF is  set  in

	     Command substitution requested when WRDE_NOCMD was	set in flags.

	     Attempt to	allocate memory	failed.

	     Shell  syntax  error,  such as unbalanced parentheses or untermi-
	     nated string.

       On successful completion, wordexp() returns 0.

       Otherwise, a non-zero value as described	in <wordexp.h> is returned  to
       indicate	 an  error.  If	wordexp() returns the value WRDE_NOSPACE, then
       pwordexp-_we_wordc and pwordexp-_we_wordv will be  updated  to  reflect
       any  words  that	 were successfully expanded. In	other cases, they will
       not be modified.

       The wordfree() function returns no value.

       No errors are defined.

       This function is	intended to be used by an application that wants to do
       all  of the shell's expansions on a word	or words obtained from a user.
       For example, if the application prompts for  a  filename	 (or  list  of
       filenames) and then uses	wordexp() to process the input,	the user could
       respond with anything that would	be valid as input to the shell.

       The WRDE_NOCMD flag is provided for applications	that, for security  or
       other  reasons,	want  to  prevent a user from executing	shell command.
       Disallowing unquoted shell special characters  also  prevents  unwanted
       side effects such as executing a	command	or writing a file.

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

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |MT-Level		     |MT-Safe			   |

       fnmatch(3C), glob(3C), attributes(5)

SunOS 5.9			  29 Dec 1996			   wordexp(3C)


Want to link to this manual page? Use this URL:

home | help