mirror of https://github.com/mkerrisk/man-pages
215 lines
5.3 KiB
Groff
215 lines
5.3 KiB
Groff
.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
|
|
.\"
|
|
.\" This is free documentation; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU General Public License as
|
|
.\" published by the Free Software Foundation; either version 2 of
|
|
.\" the License, or (at your option) any later version.
|
|
.\"
|
|
.\" The GNU General Public License's references to "object code"
|
|
.\" and "executables" are to be interpreted as the output of any
|
|
.\" document formatting or typesetting system, including
|
|
.\" intermediate and printed output.
|
|
.\"
|
|
.\" This manual is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
.\" GNU General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public
|
|
.\" License along with this manual; if not, write to the Free
|
|
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
|
|
.\" USA.
|
|
.\"
|
|
.TH WORDEXP 3 2008-06-14 "" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
wordexp, wordfree \- perform word expansion like a posix-shell
|
|
.SH SYNOPSIS
|
|
.B "#include <wordexp.h>"
|
|
.sp
|
|
.BI "int wordexp(const char *" s ", wordexp_t *" p ", int " flags );
|
|
.sp
|
|
.BI "void wordfree(wordexp_t *" p );
|
|
.sp
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.sp
|
|
.BR wordexp (),
|
|
.BR wordfree ():
|
|
_XOPEN_SOURCE
|
|
.SH DESCRIPTION
|
|
The function
|
|
.BR wordexp ()
|
|
performs a shell-like expansion of the string
|
|
.I s
|
|
and returns the result in the structure pointed to by
|
|
.IR p .
|
|
The data type
|
|
.I wordexp_t
|
|
is a structure that at least has the fields
|
|
.IR we_wordc ,
|
|
.IR we_wordv ,
|
|
and
|
|
.IR we_offs .
|
|
The field
|
|
.I we_wordc
|
|
is a
|
|
.I size_t
|
|
that gives the number of words in the expansion of
|
|
.IR s .
|
|
The field
|
|
.I we_wordv
|
|
is a
|
|
.I char **
|
|
that points to the array of words found.
|
|
The field
|
|
.I we_offs
|
|
of type
|
|
.I size_t
|
|
is sometimes (depending on
|
|
.IR flags ,
|
|
see below) used to indicate the number of initial elements in the
|
|
.I we_wordv
|
|
array that should be filled with NULLs.
|
|
.LP
|
|
The function
|
|
.BR wordfree ()
|
|
frees the allocated memory again.
|
|
More precisely, it does not free
|
|
its argument, but it frees the array
|
|
.I we_wordv
|
|
and the strings that points to.
|
|
.SS Example
|
|
First a small example.
|
|
The output is approximately that of "ls [a-c]*.c".
|
|
.LP
|
|
.nf
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
#include <wordexp.h>
|
|
|
|
int
|
|
main(int argc, char **argv)
|
|
{
|
|
wordexp_t p;
|
|
char **w;
|
|
int i;
|
|
|
|
wordexp("[a-c]*.c", &p, 0);
|
|
w = p.we_wordv;
|
|
for (i=0; i < p.we_wordc; i++)
|
|
printf("%s\en", w[i]);
|
|
wordfree(&p);
|
|
exit(EXIT_SUCCESS);
|
|
}
|
|
.fi
|
|
.SS "The string argument"
|
|
Since the expansion is the same as the expansion by the shell (see
|
|
.BR sh (1))
|
|
of the parameters to a command, the string
|
|
.I s
|
|
must not contain characters that would be illegal in shell command
|
|
parameters.
|
|
In particular, there must not be any non-escaped
|
|
newline or |, &, ;, <, >, (, ), {, } characters
|
|
outside a command substitution or parameter substitution context.
|
|
.LP
|
|
If the argument
|
|
.I s
|
|
contains a word that starts with an unquoted comment character #,
|
|
then it is unspecified whether that word and all following words
|
|
are ignored, or the # is treated as a non-comment character.
|
|
.SS "The expansion"
|
|
The expansion done consists of the following stages:
|
|
tilde expansion (replacing ~user by user's home directory),
|
|
variable substitution (replacing $FOO by the value of the environment
|
|
variable FOO), command substitution (replacing $(command) or \`command\`
|
|
by the output of command), arithmetic expansion, field splitting,
|
|
wildcard expansion, quote removal.
|
|
.LP
|
|
The result of expansion of special parameters
|
|
($@, $*, $#, $?, $\-, $$, $!, $0) is unspecified.
|
|
.LP
|
|
Field splitting is done using the environment variable $IFS.
|
|
If it is not set, the field separators are space, tab and newline.
|
|
.SS "The output array"
|
|
The array
|
|
.I we_wordv
|
|
contains the words found, followed by a NULL.
|
|
.SS "The flags argument"
|
|
The
|
|
.I flag
|
|
argument is a bitwise inclusive OR of the following values:
|
|
.TP
|
|
.B WRDE_APPEND
|
|
Append the words found to the array resulting from a previous call.
|
|
.TP
|
|
.B WRDE_DOOFFS
|
|
Insert
|
|
.I we_offs
|
|
initial NULLs in the array
|
|
.IR we_wordv .
|
|
(These are not counted in the returned
|
|
.IR we_wordc .)
|
|
.TP
|
|
.B WRDE_NOCMD
|
|
Don't do command substitution.
|
|
.TP
|
|
.B WRDE_REUSE
|
|
The parameter
|
|
.I p
|
|
resulted from a previous call to
|
|
.BR wordexp (),
|
|
and
|
|
.BR wordfree ()
|
|
was not called.
|
|
Reuse the allocated storage.
|
|
.TP
|
|
.B WRDE_SHOWERR
|
|
Normally during command substitution
|
|
.I stderr
|
|
is redirected to
|
|
.IR /dev/null .
|
|
This flag specifies that
|
|
.I stderr
|
|
is not to be redirected.
|
|
.TP
|
|
.B WRDE_UNDEF
|
|
Consider it an error if an undefined shell variable is expanded.
|
|
.SH "RETURN VALUE"
|
|
In case of success 0 is returned.
|
|
In case of error
|
|
one of the following five values is returned.
|
|
.TP
|
|
.B WRDE_BADCHAR
|
|
Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }.
|
|
.TP
|
|
.B WRDE_BADVAL
|
|
An undefined shell variable was referenced, and the
|
|
.B WRDE_UNDEF
|
|
flag
|
|
told us to consider this an error.
|
|
.TP
|
|
.B WRDE_CMDSUB
|
|
Command substitution occurred, and the
|
|
.B WRDE_NOCMD
|
|
flag told us to consider this an error.
|
|
.TP
|
|
.B WRDE_NOSPACE
|
|
Out of memory.
|
|
.TP
|
|
.B WRDE_SYNTAX
|
|
Shell syntax error, such as unbalanced parentheses or
|
|
unmatched quotes.
|
|
.SH VERSIONS
|
|
.BR wordexp ()
|
|
and
|
|
.BR wordfree ()
|
|
are provided in glibc since version 2.1.
|
|
.SH "CONFORMING TO"
|
|
POSIX.1-2001
|
|
.SH "SEE ALSO"
|
|
.BR fnmatch (3),
|
|
.BR glob (3)
|