diff options
Diffstat (limited to 'man3/wordexp.3')
| -rw-r--r-- | man3/wordexp.3 | 245 |
1 files changed, 0 insertions, 245 deletions
diff --git a/man3/wordexp.3 b/man3/wordexp.3 deleted file mode 100644 index b078707..0000000 --- a/man3/wordexp.3 +++ /dev/null @@ -1,245 +0,0 @@ -'\" t -.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) -.\" -.\" SPDX-License-Identifier: GPL-2.0-or-later -.\" -.TH wordexp 3 2023-10-31 "Linux man-pages 6.7" -.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) |