wordfree(3) on freebsd

Usage

int

void

Library

Standard C Library (libc, -lc)

Overview

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).
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.

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.

History

FreeBSD 16.0-CURRENT (2026-10-27) to FreeBSD 13.3-RELEASE: the text shown here
FreeBSD 13.2-RELEASE to FreeBSD 13.0-RELEASE
FreeBSD 12.4-RELEASE
FreeBSD 12.3-RELEASE
FreeBSD 12.2-RELEASE
FreeBSD 12.1-RELEASE
FreeBSD 12.0-RELEASE
FreeBSD 11.4-RELEASE
FreeBSD 11.3-RELEASE
FreeBSD 11.2-RELEASE
FreeBSD 11.1-RELEASE
FreeBSD 11.0-RELEASE
FreeBSD 10.4-RELEASE
FreeBSD 10.3-RELEASE
FreeBSD 10.2-RELEASE
FreeBSD 10.1-RELEASE
FreeBSD 10.0-RELEASE
FreeBSD 9.3-RELEASE
FreeBSD 9.2-RELEASE
FreeBSD 9.1-RELEASE
FreeBSD 9.0-RELEASE
FreeBSD 8.4-RELEASE
FreeBSD 8.3-RELEASE
FreeBSD 8.2-RELEASE
FreeBSD 8.1-RELEASE
FreeBSD 8.0-RELEASE
FreeBSD 7.4-RELEASE
FreeBSD 7.3-RELEASE
FreeBSD 7.2-RELEASE
FreeBSD 7.1-RELEASE
FreeBSD 7.0-RELEASE
FreeBSD 6.4-RELEASE
FreeBSD 6.3-RELEASE to FreeBSD 6.2-RELEASE
FreeBSD 6.1-RELEASE to FreeBSD 5.3-RELEASE
FreeBSD 5.2.1-RELEASE to FreeBSD 5.2-RELEASE
FreeBSD 5.1-RELEASE