wordexp(3)						     Library Functions Manual							wordexp(3)

NAME

       wordexp, wordfree - Perform word expansions

LIBRARY

       Standard C Library (libc.so, libc.a)

SYNOPSIS

       #include <wordexp.h>

       int wordexp(
	       const char *words,
	       wordexp_t *pwordexp,
	       int flags);

       void wordfree(
	       wordexp_t *pwordexp);

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       wordexp(), wordfree():  XPG4, XPG4-UNIX

       Refer to the standards(5) reference page for more information about industry standards and associated tags.

PARAMETERS

       Specifies  the  string  containing the tokens to be expanded.  Contains a pointer to a wordexp_t structure.  Contains a bit flag specifying
       the configurable aspects of the wordexp() function.

DESCRIPTION

       The wordexp() function performs word expansions equivalent to the word expansion that would be performed by the shell if  the  contents	of
       the words parameter were arguments on the command line. The list of expanded words are placed in the pwordexp parameter.

       The expansions are the same as that which would be performed by the shell if the words parameter were the part of a command line represent-
       ing the parameters to a command. Therefore, the words parameter cannot contain an unquoted newline character or any of the  unquoted  shell
       special characters:

	  |   &   ;   <   >

       except  in  the case of command substitution. The words parameter also cannot contain unquoted parentheses or braces, except in the case of
       command or variable substitution. If the words parameter contains an unquoted comment character (#) that is the beginning of a  token,  the
       wordexp()  function  may  treat	the  comment  character  as a regular character, or may interpret it as a comment indicator and ignore the
       remainder of the expression in the words parameter.

       The wordexp() function stores the number of generated words and a pointer to a list of pointers to words in the	pwordexp  parameter.  Each
       individual  field created during the field splitting or pathname expansion is a separate word in the list specified by the pwordexp parame-
       ter. The first pointer after the last token in the list is a null pointer. The expansion of special parameters *, @, #, ?, -, $, !,  and  0
       is unspecified.	The words are expanded in the following order: Tilde expansion is performed first.  Parameter expansion, command substitu-
       tion, and arithmetic expansion are performed next, from beginning to end.  Field splitting is then performed on fields generated by step 2,
       unless  the  IFS (Input Field Separators) is full.  Pathname expansion is performed, unless the set -f command is in effect.  Quote removal
       is always performed last.

       The pwordexp structure is allocated by the caller, but memory to contain the expanded tokens is allocated by  the  wordexp()  function  and
       added to the structure as needed.  The wordfree() function frees any memory associated with pwordexp() from a previous call to wordexp().

       The  value  of the flags parameter is the bitwise inclusive OR of the following constants, which are defined in the wordexp.h file: Appends
       words generated to those generated by a previous call to the wordexp() function.  Makes use of the we_offs structure.  If  the  WRDE_DOOFFS
       flag is set, the we_offs structure is used to specify the number of null pointers to add to the beginning of the we_words structure. If the
       WRDE_DOOFFS flag is not set in the first call to the wordexp() function with the pwordexp parameter, it should not  be  set  in	subsequent
       calls  to  the  wordexp()  function  with  the pwordexp parameter.  Fails if command substitution is requested.	The pwordexp parameter was
       passed to a previous successful call to the wordexp() function.	Therefore, the memory previously allocated may be reused.  Does not  redi-
       rect standard error to /dev/null.  Reports error on an attempt to expand an undefined shell variable.

       The  WRDE_APPEND flag can be used to append a new set of words to those generated by a previous call to the wordexp() function. The follow-
       ing rules apply when two or more calls to the wordexp() function are made with the same value of the pwordexp parameter and without  inter-
       vening calls to the wordfree() function: The first such call does not set the WRDE_APPEND flag.	All subsequent calls set it.  For a single
       invocation of the wordexp() function, all calls either set the WRDE_DOOFFS flag, or do not set it.  After the second  and  each	subsequent
       call,  the pwordexp parameter points to a list containing the following: Zero or more null characters, as specified by the WRDE_DOOFFS flag
       and the we_offs field of the wordexp_t structure.  Pointers to the words that were in the pwordexp parameter before the call, in  the  same
       order  as  before.   Pointers  to  the  new words generated by the latest call, in the specified order.	The count returned in the pwordexp
       parameter is the total number of words from all of the calls.  The application should not modify the pwordexp parameter between the calls.

       Unless the WRDE_SHOWERR flag is set in the flags parameter, the wordexp() function redirects standard error to /dev/null for any  utilities
       executed  as  a result of command substitution while expanding the words parameter. If the WRDE_SHOWERR flag is set, the wordexp() function
       can write messages to standard error if syntax errors are detected while expanding the words parameter.

       If any of the following conditions occurs, the wordexp() function returns the corresponding nonzero constant, which is defined in the word-
       exp.h  file.   One of the unquoted characters |, & , ;, <, >, newline, parenthesis, or braces appears in the words parameter in an inappro-
       priate context.	Reference to undefined shell variable when the WRDE_UNDEF flag is  set	in  the  flags	parameter.   Command  substitution
       requested  when	the  WRDE_NOCMD  flag is set in the flags parameter.  An attempt to allocate memory was unsuccessful.  Shell syntax error,
       such as unbalanced parentheses or unterminated string.

       The wordexp() function allows an application to perform all of the shell's expansions on a word or words obtained from a user. For example,
       if  the	application  prompts  for a filename (or a list of file names) and then uses the wordexp() function to process the input, the user
       could respond with anything that would be valid as input to the shell.

       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 to a file.

NOTES

       The wordexp() function can cause a signal to be issued.	If a user program catches the signal, wordexp() may return an error.

FILES

       Defines word expansion macros, data types, and functions.

RETURN VALUES

       If  no errors are encountered while expanding the words parameter, the wordexp() function returns a value of 0 (zero).  If an error occurs,
       the function returns a nonzero value indicating the error.

       If the wordexp() function returns the error value WRDE_NOSPACE, then the expression in the pwordexp parameter is  updated  to  reflect  any
       words that were successfully expanded. In other cases, the pwordexp parameter is not modified.

       The wordfree() function returns no value.

RELATED INFORMATION

       Functions: glob(3)

       Standards: standards(5) delim off

																	wordexp(3)