wordexp.3p (15246B)
- '\" 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 .