summaryrefslogtreecommitdiffstats
path: root/man3/wordexp.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/wordexp.3')
-rw-r--r--man3/wordexp.3245
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)