Unix/Linux Go Back    

Linux 2.6 - man page for wordexp (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)

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

       #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

       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-

       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:

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

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

	      Don't do command substitution.

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

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

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

       In  case  of  success 0 is returned.  In case of error one of the following five values is

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

	      An undefined shell variable was referenced, and the WRDE_UNDEF flag told us to con-
	      sider this an error.

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

	      Out of memory.

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

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


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

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

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

       fnmatch(3), glob(3)

       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

					    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 04:13 PM.