diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3p/wordexp.3p')
| -rw-r--r-- | upstream/mageia-cauldron/man3p/wordexp.3p | 506 |
1 files changed, 506 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3p/wordexp.3p b/upstream/mageia-cauldron/man3p/wordexp.3p new file mode 100644 index 00000000..ed59f89c --- /dev/null +++ b/upstream/mageia-cauldron/man3p/wordexp.3p @@ -0,0 +1,506 @@ +'\" et +.TH WORDEXP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wordexp, +wordfree +\(em perform word expansions +.SH SYNOPSIS +.LP +.nf +#include <wordexp.h> +.P +int wordexp(const char *restrict \fIwords\fP, wordexp_t *restrict \fIpwordexp\fP, + int \fIflags\fP); +void wordfree(wordexp_t *\fIpwordexp\fP); +.fi +.SH DESCRIPTION +The +\fIwordexp\fR() +function shall perform word expansions as described in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.6" ", " "Word Expansions", +subject to quoting as described in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.2" ", " "Quoting", +and place the list of expanded words into the structure pointed to by +.IR pwordexp . +.P +The +.IR words +argument is a pointer to a string containing one or more words to be +expanded. The expansions shall be the same as would be performed by the +command line interpreter if +.IR words +were the part of a command line representing the arguments to a +utility. Therefore, the application shall ensure that +.IR words +does not contain an unquoted +<newline> +character or any of the unquoted shell special characters +.BR '|' , +.BR '&' , +.BR ';' , +.BR '<' , +.BR '>' +except in the context of command substitution as specified in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.6.3" ", " "Command Substitution". +It also shall not contain unquoted parentheses or braces, except +in the context of command or variable substitution. The application +shall ensure that every member of +.IR words +which it expects to have expanded by +\fIwordexp\fR() +does not contain an unquoted initial comment character. The application +shall also ensure that any words which it intends to be ignored +(because they begin or continue a comment) are deleted from +.IR words . +If the argument +.IR words +contains an unquoted comment character (\c +<number-sign>) +that is the beginning of a token, +\fIwordexp\fR() +shall either treat the comment character as a regular character, or +interpret it as a comment indicator and ignore the remainder of +.IR words . +.P +The structure type +.BR wordexp_t +is defined in the +.IR <wordexp.h> +header and includes at least the following members: +.TS +center box tab(!); +cB | cB | cB +lw(1.25i)B | lw(1.25i)I | lw(2.5i). +Member Type!Member Name!Description +_ +size_t!we_wordc!Count of words matched by \fIwords\fP. +char **!we_wordv!Pointer to list of expanded words. +size_t!we_offs!T{ +Slots to reserve at the beginning of \fIpwordexp\fP\->\fIwe_wordv\fR. +T} +.TE +.P +The +\fIwordexp\fR() +function shall store the number of generated words into +\fIpwordexp\fP\->\fIwe_wordc\fP and a pointer to a list of pointers to +words in \fIpwordexp\fP\->\fIwe_wordv\fP. Each individual field created +during field splitting (see the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.6.5" ", " "Field Splitting") +or pathname expansion (see the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.6.6" ", " "Pathname Expansion") +shall be a separate word in the \fIpwordexp\fP\->\fIwe_wordv\fP +list. The words shall be in order as described in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.6" ", " "Word Expansions". +The first pointer after the last word pointer shall be a null pointer. +The expansion of special parameters described in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.5.2" ", " "Special Parameters" +is unspecified. +.P +It is the caller's responsibility to allocate the storage pointed to by +.IR pwordexp . +The +\fIwordexp\fR() +function shall allocate other space as needed, including memory +pointed to by \fIpwordexp\fP\->\fIwe_wordv\fP. The +\fIwordfree\fR() +function frees any memory associated with +.IR pwordexp +from a previous call to +\fIwordexp\fR(). +.P +The +.IR flags +argument is used to control the behavior of +\fIwordexp\fR(). +The value of +.IR flags +is the bitwise-inclusive OR of zero or more of the following constants, +which are defined in +.IR <wordexp.h> : +.IP WRDE_APPEND 14 +Append words generated to the ones from a previous call to +\fIwordexp\fR(). +.IP WRDE_DOOFFS 14 +Make use of \fIpwordexp\fP\->\fIwe_offs\fP. If this flag is set, +\fIpwordexp\fP\->\fIwe_offs\fP is used to specify how many null +pointers to add to the beginning of \fIpwordexp\fP\->\fIwe_wordv\fP. +In other words, \fIpwordexp\fP\->\fIwe_wordv\fP shall point to +\fIpwordexp\fP\->\fIwe_offs\fP null pointers, followed by +\fIpwordexp\fP\->\fIwe_wordc\fP word pointers, followed by a null +pointer. +.IP WRDE_NOCMD 14 +If the implementation supports the utilities defined in the Shell and Utilities volume of POSIX.1\(hy2017, +fail if command substitution, as specified in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.6.3" ", " "Command Substitution", +is requested. +.IP WRDE_REUSE 14 +The +.IR pwordexp +argument was passed to a previous successful call to +\fIwordexp\fR(), +and has not been passed to +\fIwordfree\fR(). +The result shall be the same as if the application had called +\fIwordfree\fR() +and then called +\fIwordexp\fR() +without WRDE_REUSE. +.IP WRDE_SHOWERR 14 +Do not redirect +.IR stderr +to +.BR /dev/null . +.IP WRDE_UNDEF 14 +Report error on an attempt to expand an undefined shell variable. +.P +The WRDE_APPEND flag can be used to append a new set of words to those +generated by a previous call to +\fIwordexp\fR(). +The following rules apply to applications when two or more calls to +\fIwordexp\fR() +are made with the same value of +.IR pwordexp +and without intervening calls to +\fIwordfree\fR(): +.IP " 1." 4 +The first such call shall not set WRDE_APPEND. All subsequent calls +shall set it. +.IP " 2." 4 +All of the calls shall set WRDE_DOOFFS, or all shall not set it. +.IP " 3." 4 +After the second and each subsequent call, +\fIpwordexp\fP\->\fIwe_wordv\fP shall point to a list containing the +following: +.RS 4 +.IP " a." 4 +Zero or more null pointers, as specified by WRDE_DOOFFS and +\fIpwordexp\fP\->\fIwe_offs\fP +.IP " b." 4 +Pointers to the words that were in the \fIpwordexp\fP\->\fIwe_wordv\fP +list before the call, in the same order as before +.IP " c." 4 +Pointers to the new words generated by the latest call, in the +specified order +.RE +.IP " 4." 4 +The count returned in \fIpwordexp\fP\->\fIwe_wordc\fP shall be the +total number of words from all of the calls. +.IP " 5." 4 +The application can change any of the fields after a call to +\fIwordexp\fR(), +but if it does it shall reset them to the original value before a +subsequent call, using the same +.IR pwordexp +value, to +\fIwordfree\fR() +or +\fIwordexp\fR() +with the WRDE_APPEND or WRDE_REUSE flag. +.P +If the implementation supports the utilities defined in the Shell and Utilities volume of POSIX.1\(hy2017, +and +.IR words +contains an unquoted character\(em\c +<newline>, +.BR '|' , +.BR '&' , +.BR ';' , +.BR '<' , +.BR '>' , +.BR '(' , +.BR ')' , +.BR '{' , +.BR '}' \(em\c +in an inappropriate context, +\fIwordexp\fR() +shall fail, and the number of expanded words shall be 0. +.P +Unless WRDE_SHOWERR is set in +.IR flags , +\fIwordexp\fR() +shall redirect +.IR stderr +to +.BR /dev/null +for any utilities executed as a result of command substitution while +expanding +.IR words . +If WRDE_SHOWERR is set, +\fIwordexp\fR() +may write messages to +.IR stderr +if syntax errors are detected while expanding +.IR words , +unless the +.IR stderr +stream has wide orientation in which case the behavior is undefined. +It is unspecified whether any write errors encountered while +outputting such messages will affect the +.IR stderr +error indicator or the value of +.IR errno . +.P +The application shall ensure that if WRDE_DOOFFS is set, then +\fIpwordexp\fP\->\fIwe_offs\fP has the same value for each +\fIwordexp\fR() +call and +\fIwordfree\fR() +call using a given +.IR pwordexp . +.P +The results are unspecified if WRDE_APPEND and WRDE_REUSE are +both specified. +.br +.P +The following constants are defined as error return values: +.IP WRDE_BADCHAR 14 +One of the unquoted characters\(em\c +<newline>, +.BR '|' , +.BR '&' , +.BR ';' , +.BR '<' , +.BR '>' , +.BR '(' , +.BR ')' , +.BR '{' , +.BR '}' \(em\c +appears in +.IR words +in an inappropriate context. +.IP WRDE_BADVAL 14 +Reference to undefined shell variable when WRDE_UNDEF is set in +.IR flags . +.IP WRDE_CMDSUB 14 +Command substitution requested when WRDE_NOCMD was set in +.IR flags . +.IP WRDE_NOSPACE 14 +Attempt to allocate memory failed. +.IP WRDE_SYNTAX 14 +Shell syntax error, such as unbalanced parentheses or unterminated +string. +.SH "RETURN VALUE" +Upon successful completion, +\fIwordexp\fR() +shall return 0. Otherwise, a non-zero value, as described in +.IR <wordexp.h> , +shall be returned to indicate an error. If +\fIwordexp\fR() +returns the value WRDE_NOSPACE, then \fIpwordexp\fP\->\fIwe_wordc\fP +and \fIpwordexp\fP\->\fIwe_wordv\fP shall be updated to reflect any +words that were successfully expanded. In other error cases, if the +WRDE_APPEND flag was specified, \fIpwordexp\fP->\fIwe_wordc\fP and +\fIpwordexp\fP->\fIwe_wordv\fP shall not be modified. +.P +The +\fIwordfree\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIwordexp\fR() +function is intended to be used by an application that wants to do all +of the shell's expansions on a word or words obtained from a user. For +example, if the application prompts for a pathname (or list of +pathnames) and then uses +\fIwordexp\fR() +to process the input, the user could respond with anything that would +be valid as input to the shell. +.P +The WRDE_NOCMD flag is provided for applications that, for security or +other reasons, want to prevent a user from executing shell commands. +Disallowing unquoted shell special characters also prevents unwanted +side-effects, such as executing a command or writing a file. +.P +POSIX.1\(hy2008 does not require the +\fIwordexp\fR() +function to be thread-safe if passed an expression referencing an +environment variable while any other thread is concurrently modifying +any environment variable; see +.IR "\fIexec\fR\^". +.P +Even though the WRDE_SHOWERR flag allows the implementation to write +messages to +.IR stderr +during command substitution or syntax errors, this standard does not +provide any way to detect write failures during the output of such +messages. +.P +Applications which use wide-character output functions with +.IR stderr +should ensure that any calls to +\fIwordexp\fR() +do not write to +.IR stderr , +by avoiding use of the WRDE_SHOWERR flag. +.SH RATIONALE +This function was included as an alternative to +\fIglob\fR(). +There had been continuing controversy over exactly what features should +be included in +\fIglob\fR(). +It is hoped that by providing +\fIwordexp\fR() +(which provides all of the shell word expansions, but which may be slow +to execute) and +\fIglob\fR() +(which is faster, but which only performs pathname expansion, without +tilde or parameter expansion) this will satisfy the majority of +applications. +.P +While +\fIwordexp\fR() +could be implemented entirely as a library routine, it is expected that +most implementations run a shell in a subprocess to do the expansion. +.P +Two different approaches have been proposed for how the required +information might be presented to the shell and the results returned. +They are presented here as examples. +.P +One proposal is to extend the +.IR echo +utility by adding a +.BR \-q +option. This option would cause +.IR echo +to add a +<backslash> +before each +<backslash> +and +<blank> +that occurs within an argument. The +\fIwordexp\fR() +function could then invoke the shell as follows: +.sp +.RS 4 +.nf + +(void) strcpy(buffer, "echo -q"); +(void) strcat(buffer, \fIwords\fP); +if ((flags & WRDE_SHOWERR) == 0) + (void) strcat(buffer, "2>/dev/null"); +f = popen(buffer, "r"); +.fi +.P +.RE +.P +The +\fIwordexp\fR() +function would read the resulting output, remove unquoted +<backslash> +characters, and break into words at unquoted +<blank> +characters. If the WRDE_NOCMD flag was set, +\fIwordexp\fR() +would have to scan +.IR words +before starting the subshell to make sure that there would be no +command substitution. In any case, it would have to scan +.IR words +for unquoted special characters. +.P +Another proposal is to add the following options to +.IR sh : +.IP "\fB\-w\fP\ \fIwordlist\fR" 6 +.br +This option provides a wordlist expansion service to applications. The +words in +.IR wordlist +shall be expanded and the following written to standard output: +.RS 6 +.IP " 1." 4 +The count of the number of words after expansion, in decimal, followed +by a null byte +.IP " 2." 4 +The number of bytes needed to represent the expanded words (not +including null separators), in decimal, followed by a null byte +.IP " 3." 4 +The expanded words, each terminated by a null byte +.P +If an error is encountered during word expansion, +.IR sh +exits with a non-zero status after writing the former to report any +words successfully expanded +.RE +.IP "\fB\-P\fP" 6 +Run in ``protected'' mode. If specified with the +.BR \-w +option, no command substitution shall be performed. +.P +With these options, +\fIwordexp\fR() +could be implemented fairly simply by creating a subprocess using +\fIfork\fR() +and executing +.IR sh +using the line: +.sp +.RS 4 +.nf + +execl(<\fIshell path\fP>, "sh", "-P", "-w", \fIwords\fP, (char *)0); +.fi +.P +.RE +.P +after directing standard error to +.BR /dev/null . +.P +It seemed objectionable for a library routine to write messages to +standard error, unless explicitly requested, so +\fIwordexp\fR() +is required to redirect standard error to +.BR /dev/null +to ensure that no messages are generated, even for commands executed +for command substitution. The WRDE_SHOWERR flag can be specified to +request that error messages be written. +.P +The WRDE_REUSE flag allows the implementation to avoid the expense of +freeing and reallocating memory, if that is possible. A minimal +implementation can call +\fIwordfree\fR() +when WRDE_REUSE is set. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfnmatch\fR\^(\|)", +.IR "\fIglob\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<wordexp.h>\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Chapter 2" ", " "Shell Command Language" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |