HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ATTRIBUTES |STANDARDS |HISTORY |EXAMPLES |SEE ALSO |COLOPHON | |
wordexp(3) Library Functions Manualwordexp(3)wordexp, wordfree - perform word expansion like a posix-shell
Standard C library (libc,-lc)
#include <wordexp.h>int wordexp(const char *restricts, wordexp_t *restrictp, intflags);void wordfree(wordexp_t *p); Feature Test Macro Requirements for glibc (seefeature_test_macros(7)):wordexp(),wordfree(): _XOPEN_SOURCE
The functionwordexp() performs a shell-like expansion of the strings and returns the result in the structure pointed to byp. The data typewordexp_t is a structure that at least has the fieldswe_wordc,we_wordv, andwe_offs. The fieldwe_wordc is asize_t that gives the number of words in the expansion ofs. The fieldwe_wordv is achar ** that points to the array of words found. The fieldwe_offs of typesize_t is sometimes (depending onflags, see below) used to indicate the number of initial elements in thewe_wordv array that should be filled with NULLs. The functionwordfree() frees the allocated memory again. More precisely, it does not free its argument, but it frees the arraywe_wordv and the strings that points to.The string argument Since the expansion is the same as the expansion by the shell (seesh(1)) of the parameters to a command, the strings 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 arguments 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 arraywe_wordv contains the words found, followed by a NULL.The flags argument Theflag 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 Insertwe_offs initial NULLs in the arraywe_wordv. (These are not counted in the returnedwe_wordc.)WRDE_NOCMD Don't do command substitution.WRDE_REUSE The argumentp resulted from a previous call towordexp(), andwordfree() was not called. Reuse the allocated storage.WRDE_SHOWERR Normally during command substitutionstderr is redirected to/dev/null. This flag specifies thatstderr 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 theWRDE_UNDEFflag told us to consider this an error.WRDE_CMDSUB Command substitution requested, but theWRDE_NOCMDflag 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, seeattributes(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 inrace:utent signifies that if any of the functionssetutent(3),getutent(3), orendutent(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 theman-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 isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-05-17wordexp(3)Pages that refer to this page:fnmatch(3), glob(3)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |