---
name: "wordexp"
section: "3"
platform: "macos"
package: "Libc"
version: "1752.120.2"
release: "macOS 26.5"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/wordexp"
---

# wordexp(3)

perform shell-style word expansions

## NAME

**wordexp** – perform shell-style word expansions

## SYNOPSIS

**#include \<wordexp.h\>**

*int*\

**wordexp**(*const char \* restrict words*, *wordexp\_t \* restrict we*, *int flags*);

*void*\

**wordfree**(*wordexp\_t \*we*);

## DESCRIPTION

The **wordexp**() function performs shell-style word expansion on *words* and places the list of words into the *we\_wordv* member of *we*, and the number of words into *we\_wordc*.

The *flags* argument is the bitwise inclusive OR of any of the following constants:

- WRDE\_APPEND

  Append the words to those generated by a previous call to **wordexp**().

- WRDE\_DOOFFS

  As many NULL pointers as are specified by the *we\_offs* member of *we* are added to the front of *we\_wordv*.

- WRDE\_NOCMD

  Disallow command substitution in *words*. See the note in BUGS before using this.

- WRDE\_REUSE

  The *we* argument was passed to a previous successful call to **wordexp**() but has not been passed to **wordfree**(). The implementation may reuse the space allocated to it.

- WRDE\_SHOWERR

  Do not redirect shell error messages to */dev/null*.

- WRDE\_UNDEF

  Report error on an attempt to expand an undefined shell variable.

The *wordexp\_t* structure is defined in ⟨wordexp.h⟩ as:

```
typedef struct {
	size_t	we_wordc;	/* count of words matched */
	char	**we_wordv;	/* pointer to list of words */
	size_t	we_offs;	/* slots to reserve in we_wordv */
} wordexp_t;
```

The **wordfree**() function frees the memory allocated by **wordexp**().

## RETURN VALUES

The **wordexp**() function returns zero if successful, otherwise it returns one of the following error codes:

- WRDE\_BADCHAR

  The *words* argument contains one of the following unquoted characters: ⟨newline⟩, ‘\|’, ‘&’, ‘;’, ‘\<’, ‘\>’, ‘(’, ‘)’, ‘{’, ‘}’.

- WRDE\_BADVAL

  An attempt was made to expand an undefined shell variable and WRDE\_UNDEF is set in *flags*.

- WRDE\_CMDSUB

  An attempt was made to use command substitution and WRDE\_NOCMD is set in *flags*.

- WRDE\_NOSPACE

  Not enough memory to store the result.

- WRDE\_SYNTAX

  Shell syntax error in *words*.

The **wordfree**() function returns no value.

## ENVIRONMENT

- IFS

  Field separator.

## EXAMPLES

Invoke the editor on all *.c* files in the current directory and */etc/motd* (error checking omitted):

```
wordexp_t we;
wordexp("${EDITOR:-vi} *.c /etc/motd", &we, 0);
execvp(we.we_wordv[0], we.we_wordv);
```

## DIAGNOSTICS

Diagnostic messages from the shell are written to the standard error output if WRDE\_SHOWERR is set in *flags*.

## SEE ALSO

[sh(1)](/sh/1.md), [fnmatch(3)](/fnmatch/3.md), [glob(3)](/glob/3.md), [popen(3)](/popen/3.md), [system(3)](/system/3.md)

## STANDARDS

The **wordexp**() and **wordfree**() functions conform to IEEE Std 1003.1-2001 (“POSIX.1”).

## BUGS

Do not pass untrusted user data to **wordexp**(), regardless of whether the WRDE\_NOCMD flag is set. The **wordexp**() function attempts to detect input that would cause commands to be executed before passing it to the shell but it does not use the same parser so it may be fooled.

The current **wordexp**() implementation does not recognize multibyte characters, since the shell (which it invokes to perform expansions) does not.