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	*restrict words, wordexp_t *restrict 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	pword-

       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>:

       WRDE_APPEND     Append words generated to the ones from a previous call
		       to wordexp().

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

       WRDE_NOCMD      Fail if command substitution is requested.

       WRDE_REUSE      The pwordexp argument was passed	to a previous success-
		       ful call	to wordexp(), and has not been passed to word-
		       free(). The result will be the same as if the  applica-
		       tion  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

       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

		   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	 word-
	   free() 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:

       WRDE_BADCHAR    One of the unquoted characters:

		       NEWLINE |   &   ;   <   >   (   )   {   }

		       appears in words	in an inappropriate 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_SYNTAX     Shell  syntax  error, such as unbalanced	parentheses or
		       unterminated 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	   |
       |Interface Stability	     |Standard			   |
       |MT-Level		     |MT-Safe			   |

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

SunOS 5.10			  1 Nov	2003			   wordexp(3C)


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

home | help