huschi.net

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 pre-
       cisely, 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 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 unescaped newline or |, &, ;, <,  >,  (,
       ),  {, } characters outside a command substitution or parameter substi-
       tution 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 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  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 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.
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.53 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)