wordfree(3p) - phpMan

WORDEXP(3P)                POSIX Programmer's Manual               WORDEXP(3P)

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.
NAME
       wordexp, wordfree - perform word expansions
SYNOPSIS
       #include <wordexp.h>
       int wordexp(const char *restrict words, wordexp_t *restrict pwordexp,
              int flags);
       void wordfree(wordexp_t *pwordexp);

DESCRIPTION
       The wordexp() function shall perform word expansions  as  described  in
       the  Shell  and  Utilities volume of IEEE Std 1003.1-2001, Section 2.6,
       Word Expansions, subject to quoting as in the Shell and Utilities  vol-
       ume  of  IEEE Std 1003.1-2001, Section 2.2, Quoting, and place the list
       of expanded words into the structure pointed to by pwordexp.
       The 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 per-
       formed by the command line interpreter if words were the part of a com-
       mand  line  representing  the  arguments  to  a utility. Therefore, the
       application shall ensure that words does not contain an unquoted  <new-
       line>  or  any  of the unquoted shell special characters '|', '&', ';',
       '<', '>' except in the context of command substitution as specified  in
       the  Shell and Utilities volume of IEEE Std 1003.1-2001, 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  words  which  it
       expects to have expanded by wordexp() does not contain an unquoted ini-
       tial 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 words. If  the  argument  words  contains  an
       unquoted  comment  character  (number  sign) that is the beginning of a
       token, wordexp() shall either treat the comment character as a  regular
       character,  or  interpret  it  as  a  comment  indicator and ignore the
       remainder of words.
       The structure type wordexp_t is defined in the <wordexp.h>  header  and
       includes at least the following members:
          Member Type Member Name Description
          size_t      we_wordc    Count of words matched by words.
          char **     we_wordv    Pointer to list of expanded words.
          size_t      we_offs     Slots to reserve at the beginning of
                                  pwordexp->we_wordv.
       The wordexp() function shall store the number of generated  words  into
       pwordexp->we_wordc  and  a  pointer  to  a list of pointers to words in
       pwordexp->we_wordv.  Each individual field created during field  split-
       ting  (see the Shell and Utilities volume of IEEE Std 1003.1-2001, Sec-
       tion 2.6.5, Field Splitting) or pathname expansion (see the  Shell  and
       Utilities  volume  of  IEEE Std 1003.1-2001,  Section  2.6.6,  Pathname
       Expansion) shall be a separate word in the pwordexp->we_wordv list. The
       words  shall be in order as described in the Shell and Utilities volume
       of  IEEE Std 1003.1-2001,  Section  2.6,  Word  Expansions.  The  first
       pointer after the last word pointer shall be a null pointer. The expan-
       sion of special parameters described in the Shell and Utilities  volume
       of  IEEE Std 1003.1-2001, Section 2.5.2, Special Parameters is unspeci-
       fied.
       It is the caller's responsibility to allocate the storage pointed to by
       pwordexp.  The wordexp() function shall allocate other space as needed,
       including memory pointed  to  by  pwordexp->we_wordv.   The  wordfree()
       function frees any memory associated with pwordexp from a previous call
       to wordexp().
       The flags argument is used to control the behavior of  wordexp().   The
       value  of flags is the bitwise-inclusive OR of zero or more of the fol-
       lowing constants, which are defined in <wordexp.h>:
       WRDE_APPEND
              Append words generated to the ones from a previous call to word-
              exp().
       WRDE_DOOFFS
              Make  use  of  pwordexp->we_offs.  If  this  flag is set, pword-
              exp->we_offs is used to specify how many null pointers to add to
              the  beginning  of  pwordexp->we_wordv.   In other words, pword-
              exp->we_wordv shall point to  pwordexp->we_offs  null  pointers,
              followed by pwordexp->we_wordc word pointers, followed by a null
              pointer.
       WRDE_NOCMD
              If the implementation supports  the  utilities  defined  in  the
              Shell and Utilities volume of IEEE Std 1003.1-2001, fail if com-
              mand substitution, as specified in the Shell and Utilities  vol-
              ume  of  IEEE Std 1003.1-2001,  Section 2.6.3, Command Substitu-
              tion, is requested.
       WRDE_REUSE
              The pwordexp argument was passed to a previous  successful  call
              to  wordexp(), and has not been passed to wordfree(). The result
              shall be the same as if the application  had  called  wordfree()
              and then called wordexp() without WRDE_REUSE.
       WRDE_SHOWERR
              Do not redirect stderr to /dev/null.
       WRDE_UNDEF
              Report  error  on  an attempt to expand an undefined shell vari-
              able.

       The WRDE_APPEND flag can be used to append a new set of words to  those
       generated by a previous call to wordexp(). The following rules apply to
       applications when two or more calls to wordexp() are made with the same
       value of pwordexp and without intervening calls to wordfree():
        1. The first such call shall not set WRDE_APPEND. All subsequent calls
           shall set it.
        2. All of the calls shall set WRDE_DOOFFS, or all shall not set it.
        3. After the second and each subsequent call, pwordexp->we_wordv shall
           point to a list containing the following:
            a. Zero  or  more  null  pointers, as specified by WRDE_DOOFFS and
               pwordexp->we_offs
            b. Pointers to the words that were in the pwordexp->we_wordv  list
               before the call, in the same order as before
            c. Pointers  to the new words generated by the latest call, in the
               specified order
        4. The count returned in pwordexp->we_wordc shall be the total  number
           of words from all of the calls.
        5. The  application can change any of the fields after a call to word-
           exp(), but if it does it shall reset them  to  the  original  value
           before  a  subsequent call, using the same pwordexp value, to word-
           free() or wordexp() with the WRDE_APPEND or WRDE_REUSE flag.
       If the implementation supports the utilities defined in the  Shell  and
       Utilities   volume  of  IEEE Std 1003.1-2001,  and  words  contains  an
       unquoted character- <newline>, '|', '&', ';', '<', '>', '(', ')',  '{',
       '}' - in an inappropriate context, wordexp() shall fail, and the number
       of expanded words shall be 0.
       Unless WRDE_SHOWERR is set in flags, wordexp() shall redirect stderr to
       /dev/null  for  any utilities executed as a result of command substitu-
       tion while expanding words.  If  WRDE_SHOWERR  is  set,  wordexp()  may
       write  messages to stderr if syntax errors are detected while expanding
       words.
       The application shall ensure that if WRDE_DOOFFS is  set,  then  pword-
       exp->we_offs  has the same value for each wordexp() call and wordfree()
       call using a given pwordexp.
       The following constants are defined as error return values:
       WRDE_BADCHAR
              One of the unquoted characters- <newline>, '|', '&',  ';',  '<',
              '>',  '(',  ')', '{', '}' - appears in words in an inappropriate
              context.
       WRDE_BADVAL
              Reference to undefined shell variable when WRDE_UNDEF is set  in
              flags.
       WRDE_CMDSUB
              Command substitution requested when WRDE_NOCMD was set in flags.
       WRDE_NOSPACE
              Attempt to allocate memory failed.
       WRDE_SYNTAX
              Shell  syntax  error, such as unbalanced parentheses or untermi-
              nated string.

RETURN VALUE
       Upon successful completion, wordexp() shall return 0. Otherwise, a non-
       zero  value, as described in <wordexp.h>, shall be returned to indicate
       an error. If wordexp() returns  the  value  WRDE_NOSPACE,  then  pword-
       exp->we_wordc  and  pwordexp->we_wordv  shall be updated to reflect any
       words that were successfully expanded. In other cases, they  shall  not
       be modified.
       The wordfree() function shall not return a value.
ERRORS
       No errors are defined.
       The following sections are informative.
EXAMPLES
       None.
APPLICATION USAGE
       The  wordexp()  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 filename (or
       list of filenames) and then uses wordexp() 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 a file.
RATIONALE
       This  function was included as an alternative to glob(). There had been
       continuing controversy over exactly what features should be included in
       glob().  It is hoped that by providing wordexp() (which provides all of
       the shell word expansions, but which may be slow to execute) and glob()
       (which  is  faster, but which only performs pathname expansion, without
       tilde or parameter expansion) this will satisfy the majority of  appli-
       cations.
       While  wordexp() could be implemented entirely as a library routine, it
       is expected that most implementations run a shell in a subprocess to do
       the expansion.
       Two different approaches have been proposed for how the required infor-
       mation might be presented to the shell and the results  returned.  They
       are presented here as examples.
       One  proposal is to extend the echo utility by adding a -q option. This
       option would cause echo to add a backslash before  each  backslash  and
       <blank>  that  occurs  within an argument. The wordexp() function could
       then invoke the shell as follows:

              (void) strcpy(buffer, "echo -q");
              (void) strcat(buffer, words);
              if ((flags & WRDE_SHOWERR) == 0)
                  (void) strcat(buffer, "2>/dev/null");
              f = popen(buffer, "r");
       The wordexp() function would read the resulting output, remove unquoted
       backslashes,  and  break  into  words  at  unquoted  <blank>s.  If  the
       WRDE_NOCMD flag was set, wordexp() would  have  to  scan  words  before
       starting  the subshell to make sure that there would be no command sub-
       stitution. In any case, it would have to scan words for  unquoted  spe-
       cial characters.
       Another proposal is to add the following options to sh:
       -w wordlist
              This  option  provides  a wordlist expansion service to applica-
              tions.  The words in wordlist shall be expanded and the  follow-
              ing written to standard output:
               1. The  count  of the number of words after expansion, in deci-
                  mal, followed by a null byte
               2. The number of bytes needed to represent the  expanded  words
                  (not  including  null separators), in decimal, followed by a
                  null byte
               3. The expanded words, each terminated by a null byte
       If an error is encountered during word expansion, sh exits with a  non-
       zero  status  after writing the former to report any words successfully
       expanded
       -P     Run in "protected" mode. If specified with  the  -w  option,  no
              command substitution shall be performed.

       With  these  options,  wordexp()  could be implemented fairly simply by
       creating a subprocess using fork() and executing sh using the line:

              execl(<shell path>, "sh", "-P", "-w", words, (char *)0);
       after directing standard error to /dev/null.
       It seemed objectionable for a library  routine  to  write  messages  to
       standard  error,  unless explicitly requested, so wordexp() is required
       to redirect standard error to /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.
       The  WRDE_REUSE  flag allows the implementation to avoid the expense of
       freeing and reallocating memory, if that is possible. A minimal  imple-
       mentation can call wordfree() when WRDE_REUSE is set.
FUTURE DIRECTIONS
       None.
SEE ALSO
       fnmatch(), glob(), the Base Definitions volume of IEEE Std 1003.1-2001,
       <wordexp.h>, the Shell and Utilities  volume  of  IEEE Std 1003.1-2001,
       Chapter 2, Shell Command Language
COPYRIGHT
       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  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 .

IEEE/The Open Group                  2003                          WORDEXP(3P)