Unix/Linux Go Back    


Linux 2.6 - man page for wordfree (linux section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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);

   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

       wordexp(), wordfree(): _XOPEN_SOURCE

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 precisely, it does not
       free its argument, but it frees the array we_wordv and the strings that points to.

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

       If  the	argument s contains a word that starts with an unquoted comment character #, then
       it is unspecified whether that word and all following 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 environ-
       ment  variable FOO), command substitution (replacing $(command) or `command` by the output
       of command), arithmetic expansion, field splitting, wildcard expansion, quote removal.

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

       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  argument  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 redirected.

       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 following 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 con-
	      sider 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.

VERSIONS
       wordexp() and wordfree() are provided in glibc since version 2.1.

CONFORMING TO
       POSIX.1-2001.

EXAMPLE
       The output of the following example program is approximately that of "ls [a-c]*.c".

       #include <stdio.h>
       #include <stdlib.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);
	   exit(EXIT_SUCCESS);
       }

SEE ALSO
       fnmatch(3), glob(3)

COLOPHON
       This page is part of release 3.55 of the Linux man-pages project.  A  description  of  the
       project,     and    information	  about    reporting	bugs,	 can	be    found    at
       http://www.kernel.org/doc/man-pages/.

					    2008-07-14				       WORDEXP(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 05:07 AM.