NAME
wordexp —
perform shell-style word
expansions
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <wordexp.h>
int
wordexp(
const
char * restrict words,
wordexp_t * restrict
pwordexp,
int flags);
void
wordfree(
wordexp_t
*pwordexp);
DESCRIPTION
The
wordexp() function performs shell-style word expansion on
words and places the list of expanded words into the
structure pointed to by
pwordexp.
The
flags argument is the bitwise inclusive OR of any of
the following constants:
-
-
WRDE_APPEND
- Append the words to those generated by a previous call to
wordexp().
-
-
WRDE_DOOFFS
- As many
NULL
pointers as are
specified by the we_offs member of
we are added to the front of
we_wordv.
-
-
WRDE_NOCMD
- Disallow command substitution in
words. See the note in
BUGS before using this.
-
-
WRDE_REUSE
- The we argument was passed to a
previous successful call to wordexp() but has not been
passed to wordfree(). The implementation may reuse the
space allocated to it.
-
-
WRDE_SHOWERR
- Do not redirect shell error messages to
/dev/null.
-
-
WRDE_UNDEF
- Report error on an attempt to expand an undefined shell
variable.
The structure type
wordexp_t includes the following members:
size_t we_wordc
char **we_wordv
size_t we_offs
The
we_wordc member is the count of generated words.
The
we_wordv member points to a list of pointers to
expanded words.
The
we_offs member is the number of slots to reserve at
the beginning of the
we_wordv member.
It is the caller's responsibility to allocate the storage pointed to by
pwordexp. The
wordexp() function
allocates other space as needed, including memory pointed to by the
we_wordv member.
The
wordfree() function frees the memory allocated by
wordexp().
IMPLEMENTATION NOTES
The
wordexp() function is implemented as a wrapper around the
undocumented
wordexp shell built-in command.
RETURN VALUES
The
wordexp() function returns zero if successful, otherwise
it returns one of the following error codes:
-
-
WRDE_BADCHAR
- The words argument contains one of
the following unquoted characters: ⟨newline⟩,
‘
|
’,
‘&
’,
‘;
’,
‘<
’,
‘>
’,
‘(
’,
‘)
’,
‘{
’,
‘}
’.
-
-
WRDE_BADVAL
- An attempt was made to expand an undefined shell variable
and
WRDE_UNDEF
is set in
flags.
-
-
WRDE_CMDSUB
- An attempt was made to use command substitution and
WRDE_NOCMD
is set in
flags.
-
-
WRDE_NOSPACE
- Not enough memory to store the result.
-
-
WRDE_SYNTAX
- Shell syntax error in words.
-
-
WRDE_ERRNO
- An internal error occured and errno
is set to indicate the error.
The
wordfree() function returns no value.
ENVIRONMENT
-
-
IFS
- Field separator.
EXAMPLES
Invoke the editor on all
.c files in the current directory and
/etc/motd (error checking omitted):
wordexp_t we;
wordexp("${EDITOR:-vi} *.c /etc/motd", &we, 0);
execvp(we->we_wordv[0], we->we_wordv);
DIAGNOSTICS
Diagnostic messages from the shell are written to the standard error output if
WRDE_SHOWERR
is set in
flags.
SEE ALSO
sh(1),
fnmatch(3),
glob(3),
popen(3),
system(3)
STANDARDS
The
wordexp() and
wordfree() functions
conform to
IEEE Std 1003.1-2001
(“POSIX.1”). Their first release was in
IEEE Std 1003.2-1992 (“POSIX.2”). The
return value
WRDE_ERRNO
is an extension.
BUGS
Do not pass untrusted user data to
wordexp(), regardless of
whether the
WRDE_NOCMD
flag is set. The
wordexp() function attempts to detect input that would cause
commands to be executed before passing it to the shell but it does not use the
same parser so it may be fooled.