|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUE | ATTRIBUTES | STANDARDS | HISTORY | EXAMPLES | SEE ALSO | COLOPHON |
|
|
|
wordexp(3) Library Functions Manual wordexp(3)
wordexp, wordfree - perform word expansion like a posix-shell
Standard C library (libc, -lc)
#include <wordexp.h>
int wordexp(const char *restrict s, wordexp_t *restrict p, int flags);
void wordfree(wordexp_t *p);
Feature Test Macro Requirements for glibc (see
feature_test_macros(7)):
wordexp(), wordfree():
_XOPEN_SOURCE
The function wordexp() performs a shell-like expansion of the
string s and returns the result in the structure pointed to by p.
The data type wordexp_t is a structure that at least has the
fields we_wordc, we_wordv, and we_offs. The field we_wordc is a
size_t that gives the number of words in the expansion of s. The
field we_wordv is a char ** that points to the array of words
found. The field we_offs of type size_t is sometimes (depending
on flags, see below) used to indicate the number of initial
elements in the we_wordv array that should be filled with NULLs.
The function wordfree() frees the allocated memory again. More
precisely, it does not free its argument, but it frees the array
we_wordv and the strings that points to.
The string argument
Since the expansion is the same as the expansion by the shell (see
sh(1)) of the parameters to a command, the string s must not
contain characters that would be illegal in shell command
parameters. In particular, there must not be any unescaped
newline or |, &, ;, <, >, (, ), {, } characters outside a command
substitution or parameter substitution context.
If the argument 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.
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.
The result of expansion of special parameters ($@, $*, $#, $?, $-,
$$, $!, $0) is unspecified.
Field splitting is done using the environment variable $IFS. If
it is not set, the field separators are space, tab, and newline.
The output array
The array we_wordv contains the words found, followed by a NULL.
The flags argument
The flag argument is a bitwise inclusive OR of the following
values:
WRDE_APPEND
Append the words found to the array resulting from a
previous call.
WRDE_DOOFFS
Insert we_offs initial NULLs in the array we_wordv. (These
are not counted in the returned we_wordc.)
WRDE_NOCMD
Don't do command substitution.
WRDE_REUSE
The argument p resulted from a previous call to wordexp(),
and wordfree() was not called. Reuse the allocated
storage.
WRDE_SHOWERR
Normally during command substitution stderr is redirected
to /dev/null. This flag specifies that stderr is not to be
redirected.
WRDE_UNDEF
Consider it an error if an undefined shell variable is
expanded.
On success, wordexp() returns 0. On failure, wordexp() returns
one of the following nonzero values:
WRDE_BADCHAR
Illegal occurrence of newline or one of |, &, ;, <, >, (,
), {, }.
WRDE_BADVAL
An undefined shell variable was referenced, and the
WRDE_UNDEF flag told us to consider this an error.
WRDE_CMDSUB
Command substitution requested, but the WRDE_NOCMD flag
told us to consider this an error.
WRDE_NOSPACE
Out of memory.
WRDE_SYNTAX
Shell syntax error, such as unbalanced parentheses or
unmatched quotes.
For an explanation of the terms used in this section, see
attributes(7).
┌────────────┬───────────────┬───────────────────────────────────┐
│ Interface │ Attribute │ Value │
├────────────┼───────────────┼───────────────────────────────────┤
│ wordexp() │ Thread safety │ MT-Unsafe race:utent const:env │
│ │ │ env sig:ALRM timer locale │
├────────────┼───────────────┼───────────────────────────────────┤
│ wordfree() │ Thread safety │ MT-Safe │
└────────────┴───────────────┴───────────────────────────────────┘
In the above table, utent in race:utent signifies that if any of
the functions setutent(3), getutent(3), or endutent(3) are used in
parallel in different threads of a program, then data races could
occur. wordexp() calls those functions, so we use race:utent to
remind users.
POSIX.1-2008.
POSIX.1-2001. glibc 2.1.
The output of the following example program is approximately that
of "ls [a-c]*.c".
#include <stdio.h>
#include <stdlib.h>
#include <wordexp.h>
int
main(void)
{
wordexp_t p;
char **w;
wordexp("[a-c]*.c", &p, 0);
w = p.we_wordv;
for (size_t i = 0; i < p.we_wordc; i++)
printf("%s\n", w[i]);
wordfree(&p);
exit(EXIT_SUCCESS);
}
fnmatch(3), glob(3)
This page is part of the man-pages (Linux kernel and C library
user-space interface documentation) project. Information about
the project can be found at
⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report
for this manual page, see
⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩.
This page was obtained from the tarball man-pages-6.15.tar.gz
fetched from
⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on
2025-08-11. If you discover any rendering problems in this HTML
version of the page, or you believe there is a better or more up-
to-date source for the page, or you have corrections or
improvements to the information in this COLOPHON (which is not
part of the original manual page), send a mail to
man-pages@man7.org
Linux man-pages 6.15 2025-05-17 wordexp(3)
Pages that refer to this page: fnmatch(3), glob(3)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|