wordfree

WORDEXP(3)		  Linux Programmer’s Manual		   WORDEXP(3)



NAME
       wordexp, wordfree - perform word expansion like a posix-shell

SYNOPSIS
       #include <wordexp.h>

       int wordexp(const char *s, wordexp_t *p, int flags);

       void wordfree(wordexp_t *p);


DESCRIPTION
       The function wordexp() performs a shell-like expansion of the string s
       and returns the result in the structure pointed to  by  p.   The	 data
       type  wordexp_t	is a structure that at least has the fields we_wordc,
       we_wordv, and we_offs.  The field we_wordc is a size_t that gives  the
       number  of  words in the expansion of s.	 The field we_wordv is a char
       ** that points to the array of words found.  The field we_offs of type
       size_t  is  sometimes (depending on flags, see below) used to indicate
       the number of initial elements in the we_wordv array  that  should  be
       filled with NULLs.

       The  function  wordfree()  frees the allocated memory again. More pre-
       cisely, it does not free its argument, but it frees the array we_wordv
       and the strings that points to.


EXAMPLE
       First  a	 small	example.  The output is approximately that of "ls [a-
       c]*.c".

       #include <stdio.h>
       #include <wordexp.h>

       int main(int argc, char **argv) {
	       wordexp_t p;
	       char **w;
	       int i;

	       wordexp("[a-c]*.c", &p, 0);
	       w = p.we_wordv;
	       for (i=0; i<p.we_wordc; i++)
		       printf("%s\n", w[i]);
	       wordfree(&p);
	       return 0;
       }

DETAILS
   The string argument
       Since the expansion is the same as the expansion	 by  the  shell	 (see
       sh(1))  of  the parameters to a command, the string s must not contain
       characters that would be illegal in shell command parameters. In	 par-
       ticular,	 there	must not be any non-escaped newline or |, &, ;, <, >,
       (, ), {, } characters outside a command substitution or parameter sub-
       stitution context.

       If the argument s contains a word that starts with an unquoted comment
       character #, then it is unspecified whether that word and all  follow-
       ing words are ignored, or the # is treated as a non-comment character.


   The expansion
       The expansion done consists of the following stages:  tilde  expansion
       (replacing  ~user  by  user’s  home  directory), variable substitution
       (replacing $FOO by the value of the environment variable FOO), command
       substitution  (replacing $(command) or ‘command‘ by the output of com-
       mand), arithmetic  expansion,  field  splitting,	 wildcard  expansion,
       quote removal.

       The result of expansion of special parameters ($@, $*, $#, $?, $-, $$,
       $!, $0) is unspecified.

       Field splitting is done using the environment variable $IFS.  If it is
       not set, the field separators are space, tab and newline.


   The output array
       The array we_wordv contains the words found, followed by a NULL.


   The flags argument
       The flag argument is a bitwise inclusive OR of the following values:

       WRDE_APPEND
	      Append  the  words found to the array resulting from a previous
	      call.

       WRDE_DOOFFS
	      Insert we_offs initial NULLs in the array we_wordv.  (These are
	      not counted in the returned we_wordc.)

       WRDE_NOCMD
	      Don’t do command substitution.

       WRDE_REUSE
	      The parameter p resulted from a previous call to wordexp(), and
	      wordfree() was not called. Reuse the allocated storage.

       WRDE_SHOWERR
	      Normally during command substitution stderr  is  redirected  to
	      /dev/null.   This flag specifies that stderr is not to be redi-
	      rected.

       WRDE_UNDEF
	      Consider	it  an	error  if  an  undefined  shell	 variable  is
	      expanded.

RETURN VALUE
       In  case of success 0 is returned. In case of error one of the follow-
       ing five values is returned.

       WRDE_BADCHAR
	      Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {,
	      }.

       WRDE_BADVAL
	      An  undefined shell variable was referenced, and the WRDE_UNDEF
	      flag told us to consider this an error.

       WRDE_CMDSUB
	      Command substitution occurred, and the WRDE_NOCMD flag told  us
	      to consider this an error.

       WRDE_NOSPACE
	      Out of memory.

       WRDE_SYNTAX
	      Shell syntax error, such as unbalanced parentheses or unmatched
	      quotes.


CONFORMING TO
       XPG4, POSIX 1003.1-2003


SEE ALSO
       fnmatch(3), glob(3)



				  2003-11-11			   WORDEXP(3)