lib/libc/gen/wordexp.3

   1 .\"     $NetBSD: wordexp.3,v 1.2 2006/04/24 20:27:34 jld Exp $
   2 .\"
   3 .\" Copyright (c) 2002 Tim J. Robbins
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/gen/wordexp.3,v 1.6 2003/09/08 19:57:14 ru Exp $
  28 .\"
  29 .Dd July 13, 2004
  30 .Dt WORDEXP 3
  31 .Os
  32 .Sh NAME
  33 .Nm wordexp
  34 .Nd "perform shell-style word expansions"
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In wordexp.h
  39 .Ft int
  40 .Fn wordexp "const char * restrict words" "wordexp_t * restrict pwordexp" "int flags"
  41 .Ft void
  42 .Fn wordfree "wordexp_t *pwordexp"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn wordexp
  46 function performs shell-style word expansion on
  47 .Fa words
  48 and places the list of expanded words into the structure pointed to by
  49 .Fa pwordexp .
  50 .Pp
  51 The
  52 .Fa flags
  53 argument is the bitwise inclusive OR of any of the following constants:
  54 .Bl -tag -width ".Dv WRDE_SHOWERR"
  55 .It Dv WRDE_APPEND
  56 Append the words to those generated by a previous call to
  57 .Fn wordexp .
  58 .It Dv WRDE_DOOFFS
  59 As many
  60 .Dv NULL
  61 pointers as are specified by the
  62 .Va we_offs
  63 member of
  64 .Fa we
  65 are added to the front of
  66 .Va we_wordv .
  67 .It Dv WRDE_NOCMD
  68 Disallow command substitution in
  69 .Fa words .
  70 See the note in
  71 .Sx BUGS
  72 before using this.
  73 .It Dv WRDE_REUSE
  74 The
  75 .Fa we
  76 argument was passed to a previous successful call to
  77 .Fn wordexp
  78 but has not been passed to
  79 .Fn wordfree .
  80 The implementation may reuse the space allocated to it.
  81 .It Dv WRDE_SHOWERR
  82 Do not redirect shell error messages to
  83 .Pa /dev/null .
  84 .It Dv WRDE_UNDEF
  85 Report error on an attempt to expand an undefined shell variable.
  86 .El
  87 .Pp
  88 The structure type
  89 .Nm wordexp_t
  90 includes the following members:
  91 .Bd -literal -offset indent
  92 size_t  we_wordc
  93 char    **we_wordv
  94 size_t  we_offs
  95 .Ed
  96 .Pp
  97 The
  98 .Fa we_wordc
  99 member is the count of generated words.
 100 .Pp
 101 The
 102 .Fa we_wordv
 103 member points to a list of pointers to expanded words.
 104 .Pp
 105 The
 106 .Fa we_offs
 107 member is the number of slots to reserve at the beginning of the
 108 .Fa we_wordv
 109 member.
 110 .Pp
 111 It is the caller's responsibility to allocate the storage pointed to by
 112 .Fa pwordexp .
 113 The
 114 .Fn wordexp
 115 function allocates other space as needed, including memory
 116 pointed to by the
 117 .Fa we_wordv
 118 member.
 119 .Pp
 120 The
 121 .Fn wordfree
 122 function frees the memory allocated by
 123 .Fn wordexp .
 124 .Sh IMPLEMENTATION NOTES
 125 The
 126 .Fn wordexp
 127 function is implemented as a wrapper around the undocumented
 128 .Ic wordexp
 129 shell built-in command.
 130 .Sh RETURN VALUES
 131 The
 132 .Fn wordexp
 133 function returns zero if successful, otherwise it returns one of the following
 134 error codes:
 135 .Bl -tag -width ".Dv WRDE_NOSPACE"
 136 .It Dv WRDE_BADCHAR
 137 The
 138 .Fa words
 139 argument contains one of the following unquoted characters:
 140 .Aq newline ,
 141 .Ql | ,
 142 .Ql \*[Am] ,
 143 .Ql \&; ,
 144 .Ql \*[Lt] ,
 145 .Ql \*[Gt] ,
 146 .Ql \&( ,
 147 .Ql \&) ,
 148 .Ql { ,
 149 .Ql } .
 150 .It Dv WRDE_BADVAL
 151 An attempt was made to expand an undefined shell variable and
 152 .Dv WRDE_UNDEF
 153 is set in
 154 .Fa flags .
 155 .It Dv WRDE_CMDSUB
 156 An attempt was made to use command substitution and
 157 .Dv WRDE_NOCMD
 158 is set in
 159 .Fa flags .
 160 .It Dv WRDE_NOSPACE
 161 Not enough memory to store the result.
 162 .It Dv WRDE_SYNTAX
 163 Shell syntax error in
 164 .Fa words .
 165 .It Dv WRDE_ERRNO
 166 An internal error occured and
 167 .Va errno
 168 is set to indicate the error.
 169 .El
 170 .Pp
 171 The
 172 .Fn wordfree
 173 function returns no value.
 174 .Sh ENVIRONMENT
 175 .Bl -tag -width ".Ev IFS"
 176 .It Ev IFS
 177 Field separator.
 178 .El
 179 .Sh EXAMPLES
 180 Invoke the editor on all
 181 .Pa .c
 182 files in the current directory
 183 and
 184 .Pa /etc/motd
 185 (error checking omitted):
 186 .Bd -literal -offset indent
 187 wordexp_t we;
 188
 189 wordexp("${EDITOR:-vi} *.c /etc/motd", \*[Am]we, 0);
 190 execvp(we-\*[Gt]we_wordv[0], we-\*[Gt]we_wordv);
 191 .Ed
 192 .Sh DIAGNOSTICS
 193 Diagnostic messages from the shell are written to the standard error output
 194 if
 195 .Dv WRDE_SHOWERR
 196 is set in
 197 .Fa flags .
 198 .Sh SEE ALSO
 199 .Xr sh 1 ,
 200 .Xr fnmatch 3 ,
 201 .Xr glob 3 ,
 202 .Xr popen 3 ,
 203 .Xr system 3
 204 .Sh STANDARDS
 205 The
 206 .Fn wordexp
 207 and
 208 .Fn wordfree
 209 functions conform to
 210 .St -p1003.1-2001 .
 211 Their first release was in
 212 .St -p1003.2-92 .
 213 The return value
 214 .Dv WRDE_ERRNO
 215 is an extension.
 216 .Sh BUGS
 217 Do not pass untrusted user data to
 218 .Fn wordexp ,
 219 regardless of whether the
 220 .Dv WRDE_NOCMD
 221 flag is set.
 222 The
 223 .Fn wordexp
 224 function attempts to detect input that would cause commands to be
 225 executed before passing it to the shell
 226 but it does not use the same parser so it may be fooled.