diff options
Diffstat (limited to 'man/man3/wordexp.3')
| -rw-r--r-- | man/man3/wordexp.3 | 245 |
1 files changed, 245 insertions, 0 deletions
diff --git a/man/man3/wordexp.3 b/man/man3/wordexp.3 new file mode 100644 index 000000000..94a2a393b --- /dev/null +++ b/man/man3/wordexp.3 @@ -0,0 +1,245 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH wordexp 3 (date) "Linux man-pages (unreleased)" +.SH NAME +wordexp, wordfree \- perform word expansion like a posix-shell +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include <wordexp.h>" +.P +.BI "int wordexp(const char *restrict " s ", wordexp_t *restrict " p \ +", int " flags ); +.BI "void wordfree(wordexp_t *" p ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wordexp (), +.BR wordfree (): +.nf + _XOPEN_SOURCE +.fi +.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. +.P +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 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 unescaped +newline or |, &, ;, <, >, (, ), {, } characters +outside a command substitution or parameter substitution context. +.P +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 \[ti]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. +.P +The result of expansion of special parameters +($@, $*, $#, $?, $\-, $$, $!, $0) is unspecified. +.P +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 argument +.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 +On success, +.BR wordexp () +returns 0. +On failure, +.BR wordexp () +returns one of the following nonzero values: +.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 requested, but 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 ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wordexp () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:utent const:env +env sig:ALRM timer locale +T} +T{ +.na +.nh +.BR wordfree () +T} Thread safety MT-Safe +.TE +.P +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (3), +.BR getutent (3), +or +.BR endutent (3) +are used in parallel in different threads of a program, +then data races could occur. +.BR wordexp () +calls those functions, +so we use race:utent to remind users. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +glibc 2.1. +.SH EXAMPLES +The output of the following example program +is approximately that of "ls [a-c]*.c". +.P +.\" SRC BEGIN (wordexp.c) +.EX +#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\en", w[i]); + wordfree(&p); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fnmatch (3), +.BR glob (3) |