|
|
Command expansion and variables
|
|
wordexp(3C) wordexp(3C) NAME
wordexp(), wordfree() - perform word expansions SYNOPSIS
DESCRIPTION
performs word expansions and places 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 are the same as would be performed by the shell (see sh-posix(1)), if words were the part of a command line representing the arguments to a utility. Therefore, words must not contain an unquoted newline character or any of the unquoted shell special characters or except in the context of shell command substi- tution. If words contains an unquoted comment character, it is treated as the beginning of a token that interprets as a comment indicator, causing the remainder of words to be ignored. The structure type is defined in the header and includes the following members: A used to keep count of words matched by words. A used as a pointer to a list of expanded words. Also a used to indicate the number of slots to reserve at the beginning of stores the number of generated words into Each individual field created during field splitting or path name expansion is a separated word in the list. The words are in order as described in shell word expansions. The first pointer after the last word pointer is a null pointer. The expansion of special parameters (such as $$ or $*) is unspecified. It is the caller's responsibility to allocate the storage pointed to by pwordexp. allocates other space as needed, including memory pointed to by frees any memory associated with pwordexp from a previous call to The flags argument is used to control the behavior of The value of flags is the bitwise inclusive OR of zero or more of the following con- stants, which are defined in Append words generated to the ones from a previous call to Make use of If this flag is set, is used to specify how many null pointers to add to the beginning of In other words, points to null pointers, followed by word pointers, followed by a null pointer. Fail if command substitution is requested. The pwordexp argument was passed to a previous successful call to and has not been passed to The result is the same as if the application had called and then called without Do not redirect stderr to Report error on an attempt to expand an undefined shell variable. The flag can be used to append a new set of words to those generated by a previous call to The following rules apply when two or more calls to are made with the same value of pwordexp and without intervening calls to o The first call must not set All subsequent calls must set it. o All of the calls must set or all must not set it. o After the second and each subsequent call, points to a list containing the following: o Zero or more null pointers, as specified by and o Pointers to the words that were in the list before the call, in the same order as before. o Pointers to the new words generated by the latest call, in the specified order. o The count returned in is the total number of words from all of the calls. o The application can change any of the fields after a call to but if it does, it must reset them to the original value before a subsequent call, using the same pwordexp value, to or with the or flag. If words contains an unquoted newline, parentheses, or curly brackets in an inappropriate context, fails, and the number of expanded words is zero. Unless is set in flags, redirects stderr to for any utilities executed as a result of command substitution while expanding words. If is set, writes messages to stderr if syntax errors are detected while expanding words. If is set, has the same value for each call and the call using a given RETURN VALUE
Upon successful completion, returns zero; otherwise, it returns a nonzero value defined in to indicate the error: One of the unquoted characters parentheses, or braces appears in words in an inappropriate context. Reference to undefined shell variable when is set in flags. Command substitution requested when was set in flags. Attempt to allocate memory failed. Shell syntax error such as unbalanced parentheses or unterminated string. Internal error. If returns the error value and are updated to reflect any words that were successfully expanded. In other cases, they are not modified. AUTHOR
and were developed by OSF and HP. SEE ALSO
sh-posix(1), fnmatch(3C), glob(3C), regexp(5), thread_safety(5). STANDARDS CONFORMANCE
wordexp(3C)
