libc/gen/wordexp.3

    wordexp.3 revision 289938

 Copyright (c) 2002 Tim J. Robbins
 All rights reserved.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 1. Redistributions of source code must retain the above copyright
 notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright
 notice, this list of conditions and the following disclaimer in the
 documentation and/or other materials provided with the distribution.

 THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 SUCH DAMAGE.

 $FreeBSD: stable/10/lib/libc/gen/wordexp.3 289938 2015-10-25 17:17:50Z jilles $

.Dd September 30, 2015
.Dt WORDEXP 3
.Os
.Sh NAME
.Nm wordexp
.Nd "perform shell-style word expansions"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
n wordexp.h .Ft int
.Fn wordexp "const char * restrict words" "wordexp_t * restrict we" "int flags"
.Ft void
.Fn wordfree "wordexp_t *we"
.Sh DESCRIPTION
The
.Fn wordexp
function performs shell-style word expansion on
.Fa words
and places the list of words into the
.Va we_wordv
member of
.Fa we ,
and the number of words into
.Va we_wordc .
p
The
.Fa flags
argument is the bitwise inclusive OR of any of the following constants:
l -tag -width ".Dv WRDE_SHOWERR" t Dv WRDE_APPEND Append the words to those generated by a previous call to
.Fn wordexp .
t Dv WRDE_DOOFFS As many
.Dv NULL
pointers as are specified by the
.Va we_offs
member of
.Fa we
are added to the front of
.Va we_wordv .
t Dv WRDE_NOCMD Disallow command substitution in
.Fa words .
See the note in
.Sx BUGS
before using this.
t Dv WRDE_REUSE The
.Fa we
argument was passed to a previous successful call to
.Fn wordexp
but has not been passed to
.Fn wordfree .
The implementation may reuse the space allocated to it.
t Dv WRDE_SHOWERR Do not redirect shell error messages to
a /dev/null .
t Dv WRDE_UNDEF Report error on an attempt to expand an undefined shell variable.
.El
p
The
.Vt wordexp_t
structure is defined in
n wordexp.h as:
d -literal -offset indent typedef struct {
 size_t we_wordc; /* count of words matched */
 char **we_wordv; /* pointer to list of words */
 size_t we_offs; /* slots to reserve in we_wordv */
} wordexp_t;
.Ed
p
The
.Fn wordfree
function frees the memory allocated by
.Fn wordexp .
.Sh IMPLEMENTATION NOTES
The
.Fn wordexp
function is implemented using the undocumented
c freebsd_wordexp shell built-in command.
.Sh RETURN VALUES
The
.Fn wordexp
function returns zero if successful, otherwise it returns one of the following
error codes:
l -tag -width ".Dv WRDE_NOSPACE" t Dv WRDE_BADCHAR The
.Fa words
argument contains one of the following unquoted characters:
.Aq newline ,
.Ql | ,
.Ql & ,
.Ql ; ,
.Ql < ,
.Ql > ,
.Ql ( ,
.Ql ) ,
.Ql { ,
.Ql } .
t Dv WRDE_BADVAL An attempt was made to expand an undefined shell variable and
.Dv WRDE_UNDEF
is set in
.Fa flags .
t Dv WRDE_CMDSUB An attempt was made to use command substitution and
.Dv WRDE_NOCMD
is set in
.Fa flags .
t Dv WRDE_NOSPACE Not enough memory to store the result.
t Dv WRDE_SYNTAX Shell syntax error in
.Fa words .
.El
p
The
.Fn wordfree
function returns no value.
.Sh ENVIRONMENT
l -tag -width ".Ev IFS" t Ev IFS Field separator.
.El
.Sh EXAMPLES
Invoke the editor on all
a .c
files in the current directory
and
a /etc/motd
(error checking omitted):
d -literal -offset indent wordexp_t we;

wordexp("${EDITOR:-vi} *.c /etc/motd", &we, 0);
execvp(we.we_wordv[0], we.we_wordv);
.Ed
.Sh DIAGNOSTICS
Diagnostic messages from the shell are written to the standard error output
if
.Dv WRDE_SHOWERR
is set in
.Fa flags .
.Sh SEE ALSO
.Xr sh 1 ,
.Xr fnmatch 3 ,
.Xr glob 3 ,
.Xr popen 3 ,
.Xr system 3
.Sh STANDARDS
The
.Fn wordexp
and
.Fn wordfree
functions conform to
.St -p1003.1-2001 .
.Sh BUGS
The current
.Fn wordexp
implementation does not recognize multibyte characters other than UTF-8, since
the shell (which it invokes to perform expansions) does not.
.Sh SECURITY CONSIDERATIONS
Pathname generation may create output that is exponentially larger than the
input size.
p
Although this implementation detects command substitution reliably for
.Dv WRDE_NOCMD ,
the attack surface remains fairly large.
Also, some other implementations
(such as older versions of this one)
may execute command substitutions even if
.Dv WRDE_NOCMD
is set.