wordexp.3   [plain text]


.\"
.\" 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: src/lib/libc/gen/wordexp.3,v 1.6 2003/09/08 19:57:14 ru Exp $
.\"
.Dd December 27, 2002
.Dt WORDEXP 3
.Os
.Sh NAME
.Nm wordexp
.Nd "perform shell-style word expansions"
.Sh SYNOPSIS
.In wordexp.h
.Ft int
.Fo wordexp
.Fa "const char *restrict words"
.Fa "wordexp_t *restrict pwordexp"
.Fa "int flags"
.Fc
.Ft void
.Fo wordfree
.Fa "wordexp_t *pwordexp"
.Fc
.Sh DESCRIPTION
The
.Fn wordexp
function performs shell-style word expansion on
.Fa words .
It places the list of words into the
.Va we_wordv
member of
.Fa pwordexp
and the number of words into
.Va we_wordc .
.Pp
The
.Fa flags
argument (see
.Sx BUGS )
is the bitwise inclusive OR of any of the following constants:
.Bl -tag -width ".Dv WRDE_SHOWERR"
.It Dv WRDE_APPEND
Append the words to those generated by a previous call to
.Fn wordexp .
.It Dv WRDE_DOOFS
As many
.Dv NULL
pointers as are specified by the
.Va we_offs
member of
.Fa pwordexp
are added to the front of
.Va we_wordv .
.It Dv WRDE_NOCMD
Disallow command substitution in
.Fa words .
See the note in
.Sx BUGS
before using this.
.It Dv WRDE_REUSE
The
.Fa pwordexp
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.
.It Dv WRDE_SHOWERR
Do not redirect shell error messages to
.Pa /dev/null .
.It Dv WRDE_UNDEF
Report error on an attempt to expand an undefined shell variable.
.El
.Pp
The
.Vt wordexp_t
structure is defined in
.In wordexp.h
as:
.Bd -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
.Pp
The
.Fn wordfree
function frees the memory allocated by
.Fn wordexp .
.Sh RETURN VALUES
The
.Fn wordexp
function returns zero if successful, otherwise it returns one of the following
error codes:
.Bl -tag -width ".Dv WRDE_NOSPACE"
.It 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 } .
.It Dv WRDE_BADVAL
An attempt was made to expand an undefined shell variable and
.Dv WRDE_UNDEF
is set in
.Fa flags .
.It Dv WRDE_CMDSUB
An attempt was made to use command substitution and
.Dv WRDE_NOCMD
is set in
.Fa flags .
.It Dv WRDE_NOSPACE
Not enough memory to store the result.
.It Dv WRDE_SYNTAX
Shell syntax error in
.Fa words .
.El
.Pp
The
.Fn wordfree
function returns no value.
.Sh EXAMPLES
Invoke the editor on all
.Pa .c
files in the current directory
and
.Pa /etc/motd
(error checking omitted):
.Bd -literal -offset indent
wordexp_t pwordexp;

wordexp("${EDITOR:-vi} *.c /etc/motd", &pwordexp, 0);
execvp(pwordexp->we_wordv[0], pwordexp->we_wordv);
.Ed
.Sh SEE ALSO
.Xr sh 1 ,
.Xr fnmatch 3 ,
.Xr glob 3 ,
.Xr popen 3 ,
.Xr system 3
.Sh BUGS
This version of
.Fn wordexp
ignores the value of the
.Fa flags
argument.
.Sh COPYRIGHT
Copyright 1995-2002 University Corporation for Atmospheric Research/Unidata
.Pp
Portions of this software were developed by the Unidata Program at the 
University Corporation for Atmospheric Research.