lib/libc/gen/wordexp.3

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