---
name: "wordexp"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/wordexp"
---

# wordexp(3)

perform shell-style word expansions

## NAME

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

## LIBRARY

Standard C Library (libc, -lc)

## 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**().

## IMPLEMENTATION NOTES

The **wordexp**() function is implemented using the undocumented **freebsd\_wordexp** shell built-in command.

## 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 error after successful parsing, such as an attempt to expand an undefined shell variable with WRDE\_UNDEF 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 or an error during [fork(2)](/fork/2.md).

- 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

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

## SECURITY CONSIDERATIONS

Pathname generation may create output that is exponentially larger than the input size.

Although this implementation detects command substitution reliably for WRDE\_NOCMD, the attack surface remains fairly large. Also, some other implementations (such as older versions of this one) may execute command substitutions even if WRDE\_NOCMD is set.