Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 245 insertions, 0 deletions

diff --git a/man/man3/wordexp.3 b/man/man3/wordexp.3
new file mode 100644
index 0000000..945befc
--- /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 2024-05-02 "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)