man3/wordexp.3

   1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, write to the Free
  20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  21 .\" USA.
  22 .\"
  23 .TH WORDEXP 3 2003-11-11  "" "Linux Programmer's Manual"
  24 .SH NAME
  25 wordexp, wordfree \- perform word expansion like a posix-shell
  26 .SH SYNOPSIS
  27 .sp
  28 .B "#include <wordexp.h>"
  29 .sp
  30 .BI "int wordexp(const char *" s ", wordexp_t *" p ", int " flags );
  31 .sp
  32 .BI "void wordfree(wordexp_t *" p );
  33 .sp
  34 .SH DESCRIPTION
  35 The function
  36 .B wordexp()
  37 performs a shell-like expansion of the string
  38 .I s
  39 and returns the result in the structure pointed to by
  40 .IR p .
  41 The data type
  42 .B wordexp_t
  43 is a structure that at least has the fields
  44 .IR we_wordc ,
  45 .IR we_wordv ,
  46 and
  47 .IR we_offs .
  48 The field
  49 .I we_wordc
  50 is a
  51 .B size_t
  52 that gives the number of words in the expansion of
  53 .IR s .
  54 The field
  55 .I we_wordv
  56 is a
  57 .B char **
  58 that points to the array of words found.
  59 The field
  60 .I we_offs
  61 of type
  62 .B size_t
  63 is sometimes (depending on
  64 .IR flags ,
  65 see below) used to indicate the number of initial elements in the
  66 .I we_wordv
  67 array that should be filled with NULLs.
  68 .LP
  69 The function
  70 .B wordfree()
  71 frees the allocated memory again. More precisely, it does not free
  72 its argument, but it frees the array
  73 .I we_wordv
  74 and the strings that points to.
  75
  76 .SH EXAMPLE
  77 First a small example. The output is approximately that of "ls [a-c]*.c".
  78 .LP
  79 .nf
  80 #include <stdio.h>
  81 #include <wordexp.h>
  82
  83 int main(int argc, char **argv) {
  84         wordexp_t p;
  85         char **w;
  86         int i;
  87
  88         wordexp("[a-c]*.c", &p, 0);
  89         w = p.we_wordv;
  90         for (i=0; i<p.we_wordc; i++)
  91                 printf("%s\en", w[i]);
  92         wordfree(&p);
  93         return 0;
  94 }
  95 .fi
  96 .SH DETAILS
  97 .SS "The string argument"
  98 Since the expansion is the same as the expansion by the shell (see
  99 .BR sh (1))
 100 of the parameters to a command, the string
 101 .I s
 102 must not contain characters that would be illegal in shell command
 103 parameters. In particular, there must not be any non-escaped
 104 newline or |, &, ;, <, >, (, ), {, } characters
 105 outside a command substitution or parameter substitution context.
 106 .LP
 107 If the argument
 108 .I s
 109 contains a word that starts with an unquoted comment character #,
 110 then it is unspecified whether that word and all following words
 111 are ignored, or the # is treated as a non-comment character.
 112
 113 .SS "The expansion"
 114 The expansion done consists of the following stages:
 115 tilde expansion (replacing ~user by user's home directory),
 116 variable substitution (replacing $FOO by the value of the environment
 117 variable FOO), command substitution (replacing $(command) or `command`
 118 by the output of command), arithmetic expansion, field splitting,
 119 wildcard expansion, quote removal.
 120 .LP
 121 The result of expansion of special parameters
 122 ($@, $*, $#, $?, $-, $$, $!, $0) is unspecified.
 123 .LP
 124 Field splitting is done using the environment variable $IFS.
 125 If it is not set, the field separators are space, tab and newline.
 126
 127 .SS "The output array"
 128 The array
 129 .I we_wordv
 130 contains the words found, followed by a NULL.
 131
 132 .SS "The flags argument"
 133 The
 134 .I flag
 135 argument is a bitwise inclusive OR of the following values:
 136 .TP
 137 .B WRDE_APPEND
 138 Append the words found to the array resulting from a previous call.
 139 .TP
 140 .B  WRDE_DOOFFS
 141 Insert
 142 .I we_offs
 143 initial NULLs in the array
 144 .IR we_wordv .
 145 (These are not counted in the returned
 146 .IR we_wordc .)
 147 .TP
 148 .B  WRDE_NOCMD
 149 Don't do command substitution.
 150 .TP
 151 .B WRDE_REUSE
 152 The parameter
 153 .I p
 154 resulted from a previous call to
 155 .BR wordexp() ,
 156 and
 157 .BR wordfree()
 158 was not called. Reuse the allocated storage.
 159 .TP
 160 .B WRDE_SHOWERR
 161 Normally during command substitution
 162 .I stderr
 163 is redirected to
 164 .IR /dev/null .
 165 This flag specifies that
 166 .I stderr
 167 is not to be redirected.
 168 .TP
 169 .B WRDE_UNDEF
 170 Consider it an error if an undefined shell variable is expanded.
 171 .SH "RETURN VALUE"
 172 In case of success 0 is returned. In case of error
 173 one of the following five values is returned.
 174 .TP
 175 .B WRDE_BADCHAR
 176 Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }.
 177 .TP
 178 .B WRDE_BADVAL
 179 An undefined shell variable was referenced, and the WRDE_UNDEF flag
 180 told us to consider this an error.
 181 .TP
 182 .B WRDE_CMDSUB
 183 Command substitution occurred, and the WRDE_NOCMD flag
 184 told us to consider this an error.
 185 .TP
 186 .B WRDE_NOSPACE
 187 Out of memory.
 188 .TP
 189 .B WRDE_SYNTAX
 190 Shell syntax error, such as unbalanced parentheses or
 191 unmatched quotes.
 192
 193 .SH "CONFORMING TO"
 194 XPG4, POSIX 1003.1-2003
 195
 196 .SH "SEE ALSO"
 197 .BR fnmatch (3),
 198 .BR glob (3)