Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
WORDEXP(3)		   Linux Programmer's Manual		    WORDEXP(3)

NAME
       wordexp,	wordfree - perform word	expansion like a posix-shell

SYNOPSIS
       #include	<wordexp.h>

       int wordexp(const char *s, wordexp_t *p,	int flags);

       void wordfree(wordexp_t *p);

   Feature Test	Macro Requirements for glibc (see feature_test_macros(7)):

       wordexp(), wordfree(): _XOPEN_SOURCE

DESCRIPTION
       The  function wordexp() performs	a shell-like expansion of the string s
       and returns the result in the structure pointed to by p.	 The data type
       wordexp_t  is  a	 structure  that  at  least  has  the fields we_wordc,
       we_wordv, and we_offs.  The field we_wordc is a size_t that  gives  the
       number of words in the expansion	of s.  The field we_wordv is a char **
       that points to the array	of words found.	 The  field  we_offs  of  type
       size_t  is  sometimes  (depending on flags, see below) used to indicate
       the number of initial elements in the we_wordv  array  that  should  be
       filled with NULLs.

       The  function  wordfree()  frees	the allocated memory again.  More pre-
       cisely, it does not free	its argument, but it frees the array  we_wordv
       and the strings that points to.

   The string argument
       Since  the  expansion  is  the  same as the expansion by	the shell (see
       sh(1)) of the parameters	to a command, the string s  must  not  contain
       characters  that	would be illegal in shell command parameters.  In par-
       ticular,	there must not be any unescaped	newline	or |, &, ;, <,	>,  (,
       ),  {, }	characters outside a command substitution or parameter substi-
       tution context.

       If the argument s contains a word that starts with an unquoted  comment
       character #, then it is unspecified whether that	word and all following
       words are ignored, or the # is treated as a non-comment character.

   The expansion
       The expansion done consists of the following  stages:  tilde  expansion
       (replacing  ~user by user's home	directory), variable substitution (re-
       placing $FOO by the value of the	 environment  variable	FOO),  command
       substitution  (replacing	 $(command) or `command` by the	output of com-
       mand), arithmetic expansion, field splitting, wildcard expansion, quote
       removal.

       The  result of expansion	of special parameters ($@, $*, $#, $?, $-, $$,
       $!, $0) is unspecified.

       Field splitting is done using the environment variable $IFS.  If	it  is
       not set,	the field separators are space,	tab and	newline.

   The output array
       The array we_wordv contains the words found, followed by	a NULL.

   The flags argument
       The flag	argument is a bitwise inclusive	OR of the following values:

       WRDE_APPEND
	      Append  the  words  found	to the array resulting from a previous
	      call.

       WRDE_DOOFFS
	      Insert we_offs initial NULLs in the array	we_wordv.  (These  are
	      not counted in the returned we_wordc.)

       WRDE_NOCMD
	      Don't do command substitution.

       WRDE_REUSE
	      The  argument  p resulted	from a previous	call to	wordexp(), and
	      wordfree() was not called.  Reuse	the allocated storage.

       WRDE_SHOWERR
	      Normally during command substitution  stderr  is	redirected  to
	      /dev/null.   This	 flag specifies	that stderr is not to be redi-
	      rected.

       WRDE_UNDEF
	      Consider it an error if an undefined shell variable is expanded.

RETURN VALUE
       In case of success 0 is returned.  In case of error one of the  follow-
       ing five	values is returned.

       WRDE_BADCHAR
	      Illegal  occurrence of newline or	one of |, &, ;,	<, >, (, ), {,
	      }.

       WRDE_BADVAL
	      An undefined shell variable was referenced, and  the  WRDE_UNDEF
	      flag told	us to consider this an error.

       WRDE_CMDSUB
	      Command  substitution  occurred, and the WRDE_NOCMD flag told us
	      to consider this an error.

       WRDE_NOSPACE
	      Out of memory.

       WRDE_SYNTAX
	      Shell syntax error, such as unbalanced parentheses or  unmatched
	      quotes.

VERSIONS
       wordexp() and wordfree()	are provided in	glibc since version 2.1.

CONFORMING TO
       POSIX.1-2001.

EXAMPLE
       The  output  of	the following example program is approximately that of
       "ls [a-c]*.c".

       #include	<stdio.h>
       #include	<stdlib.h>
       #include	<wordexp.h>

       int
       main(int	argc, char **argv)
       {
	   wordexp_t p;
	   char	**w;
	   int i;

	   wordexp("[a-c]*.c", &p, 0);
	   w = p.we_wordv;
	   for (i = 0; i < p.we_wordc; i++)
	       printf("%s\n", w[i]);
	   wordfree(&p);
	   exit(EXIT_SUCCESS);
       }

SEE ALSO
       fnmatch(3), glob(3)

COLOPHON
       This page is part of release 3.74 of the	Linux  man-pages  project.   A
       description  of	the project, information about reporting bugs, and the
       latest	 version    of	  this	  page,	   can	   be	  found	    at
       http://www.kernel.org/doc/man-pages/.

				  2008-07-14			    WORDEXP(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | VERSIONS | CONFORMING TO | EXAMPLE | SEE ALSO | COLOPHON

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=wordexp&sektion=3&manpath=Debian+8.1.0>

home | help