Index for Section 3

Alphabetical listing for W

Bottom of page

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
  words	    Specifies the string containing the tokens to be expanded.

  pwordexp  Contains a pointer to a wordexp_t structure.

  flags	    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 representing 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 parameter. 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:

   1.  Tilde expansion is performed first.

   2.  Parameter expansion, command substitution, and arithmetic expansion
       are performed next, from beginning to end.

   3.  Field splitting is then performed on fields generated by step 2,
       unless the IFS (Input Field Separators) is full.

   4.  Pathname expansion is performed, unless the set -f command is in
       effect.

   5.  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:

  WRDE_APPEND
	    Appends words generated to those generated by a previous call to
	    the wordexp() function.

  WRDE_DOOFFS
	    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.

  WRDE_NOCMD
	    Fails if command substitution is requested.

  WRDE_REUSE
	    The pwordexp parameter was passed to a previous successful call
	    to the wordexp() function.	Therefore, the memory previously
	    allocated may be reused.

  WRDE_SHOWERR
	    Does not redirect standard error to /dev/null.

  WRDE_UNDEF
	    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 following rules
  apply when two or more calls to the wordexp() function are made with the
  same value of the pwordexp parameter and without intervening 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 wordexp.h file.

  [WRDE_BADCHAR]
	    One of the unquoted characters |, & , ;, <, >, newline,
	    parenthesis, or braces appears in the words parameter in an
	    inappropriate context.

  [WRDE_BADVAL]
	    Reference to undefined shell variable when the WRDE_UNDEF flag is
	    set in the flags parameter.

  [WRDE_CMDSUB]
	    Command substitution requested when the WRDE_NOCMD flag is set in
	    the flags parameter.

  [WRDE_NOSPACE]
	    An attempt to allocate memory was unsuccessful.

  [WRDE_SYNTAX]
	    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
  /usr/include/wordexp.h
	    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)

Index for Section 3

Alphabetical listing for W

Top of page