Unix/Linux Go Back    


Linux 2.6 - man page for wordexp (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

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 Utili-
       ties volume of IEEE Std 1003.1-2001, Section 2.6, Word Expansions, subject to  quoting  as
       in the Shell and Utilities volume 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 performed by the command line interpreter if
       words were the part of a command line representing the arguments to a utility.  Therefore,
       the  application  shall ensure that words does not contain an unquoted <newline> 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 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	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   splitting   (see   the   Shell   and	 Utilities   volume    of
       IEEE Std 1003.1-2001, Section 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 expansion of
       special parameters described in the Shell and Utilities	volume	of  IEEE Std 1003.1-2001,
       Section 2.5.2, Special Parameters is unspecified.

       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 following constants, which are defined in
       <wordexp.h>:

       WRDE_APPEND
	      Append words generated to the ones from a previous call to wordexp().

       WRDE_DOOFFS
	      Make use of pwordexp->we_offs. If this flag is set, pwordexp->we_offs  is  used  to
	      specify  how  many null pointers to add to the beginning of pwordexp->we_wordv.  In
	      other words, pwordexp->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 command substitution, as specified  in  the
	      Shell  and Utilities volume of IEEE Std 1003.1-2001, Section 2.6.3, Command Substi-
	      tution, 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 applica-
	      tion 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 variable.

       The WRDE_APPEND flag can be used to append a new set of words to those generated by a pre-
       vious  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 wordexp(), but if it does
	   it  shall  reset  them  to the original value before a subsequent call, using the same
	   pwordexp value, to wordfree() 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  substitution  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  pwordexp->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 unterminated 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 pwordexp->we_wordc and pwordexp->we_wordv  shall  be  updated  to
       reflect any words that were successfully expanded. In other cases, they shall not be modi-
       fied.

       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 appli-
       cation 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  char-
       acters 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 contro-
       versy over exactly what features should be included in glob().  It is hoped that  by  pro-
       viding  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, with-
       out tilde or parameter expansion) this will satisfy the majority of applications.

       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 information might be pre-
       sented 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 com-
       mand substitution. In any case, it would have to scan words for unquoted  special  charac-
       ters.

       Another proposal is to add the following options to sh:

       -w wordlist

	      This  option  provides  a wordlist expansion service to applications.  The words in
	      wordlist shall be expanded and the following written to standard output:

	       1. The count of the number of words after expansion, in	decimal,  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 substitu-
       tion. 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  reallo-
       cating  memory,	if  that  is  possible. A minimal implementation 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				       WORDEXP(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 09:38 AM.