WORDEXP(3)

ИМЯ
wordexp, wordfree - дополняет слово как оболочка posix

ОБЗОР
#include <wordexp.h>

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

void wordfree(wordexp_t *p);

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

wordexp(), wordfree(): _XOPEN_SOURCE

ОПИСАНИЕ
Функция wordexp() выполняет раскрытие строки s также, как это делается в оболочке командной строки, и возвращает результат в структуре, на которую указывает p. Тип данных wordexp_t — структура, которая содержит, по крайней мере, поля we_wordc, we_wordv и we_offs. Поле we_wordc имеет тип size_t и содержит количество слов в раскрытой s. Поле we_wordv имеет тип char ** и указывает на массив найденных слов. Поле we_offs имеет тип size_t и (в зависимости от flags, см. далее) используется для указания количества начальных элементов в массиве we_wordv, которые должны быть заполнены NULL.

Функция wordfree() освобождает ранее выделенную память. Более точно, она не освобождает память своего аргумента, а освобождает память, занятую под массив we_wordv и строки, которые в нём содержатся.

  Строковый аргумент
Так как дополнение производится согласно правилам оболочки командной строки (см. sh(1)) по преобразованию параметров в команду, строка s не должна содержать символы, которые запрещено передавать в параметрах команд оболочки. В частности, не должно быть неэкранированных символов новой строки или |, &, ;, <, >, (, ), {, } вне контекста подстановки команды или параметра.

Если аргумент s содержит слово, которое начинается с символа комментария #, находящегося не в кавычках, то такая ситуация является неопределённой, и непонятно, нужно ли игнорировать слово или все слова, или не считать # символом комментария.

  Дополнение
Дополнение выполняется в несколько этапов: дополнение тильды (замена ~user на домашний каталог пользователя), подстановка переменной (замена $FOO значением переменной окружения FOO), подстановка команды (замена $(команда) или `команда` результатом выполнения команды), арифметические действия, разделение на поля, подстановка шаблонных символов (wildcard), удаление кавычек.

Результат дополнения специальных параметров ($@, $*, $#, $?, $-, $$, $!, $0) не определён.

Разделение на поля выполняется с помощью переменной окружения $IFS. Если она не установлена, то разделителями полей считаются пробел, табуляция и символ новой строки.

  Массив результата
Массив we_wordv содержит найденные слова и заканчивается NULL.

  Аргумент флагов
Аргумент flag представляет собой побитовое объединяющее ИЛИ следующих значений:

WRDE_APPEND
    Добавлять найденные слова в массив, полученный в результате предыдущего вызова.

WRDE_DOOFFS
    Вставить we_offs начальных NULL в массив we_wordv (они не считаются в конечном we_wordc).

WRDE_NOCMD
    Не выполнять подстановку команд.

WRDE_REUSE
    Аргумент p получен от предыдущего вызова wordexp(), и функция wordfree() не была вызвана. Повторно использовать выделенное пространство.

WRDE_SHOWERR
    Обычно, во время подстановки команды вывод stderr перенаправляется в /dev/null. Этим флагом задаётся отмена такого перенаправления stderr.

WRDE_UNDEF
    Считать ошибкой, если не определена раскрываемая переменная оболочки.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении возвращается 0. В случае ошибки возвращается одно из следующих пяти значений:

WRDE_BADCHAR
    Недопустимое появление символа новой строки или одного из символов |, &, ;, <, >, (, ), {, }.

WRDE_BADVAL
    Указана неопределённая переменная оболочки и установлен флаг WRDE_UNDEF.

WRDE_CMDSUB
    Запрошена подстановка команды, но установлен флаг WRDE_NOCMD, указывающий считать это ошибкой.

WRDE_NOSPACE
    Не хватает памяти.

WRDE_SYNTAX
    Синтаксическая ошибка оболочки, например незакрытая скобка или кавычка.

ВЕРСИИ
Функции wordexp() и wordfree() определены в glibc начиная с версии 2.1.

АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
Интерфейс | Атрибут | Значение
wordexp() | Безвредность в нитях | MT-Unsafe race:utent const:env env sig:ALRM timer locale
wordfree() | Безвредность в нитях | MT-Safe

В приведённой выше таблице utent в race:utent означает, что если любая из функций setutent(3), getutent(3) или endutent(3) используется одновременно в нескольких нитях программы, то может возникнуть состязательность по данным. Эти функции вызываются из wordexp(), поэтому мы используем race:utent для напоминания.

СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

ПРИМЕР
Результатом следующего примера будет таким же что и при выполнении команды «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);
    }

СМОТРИТЕ ТАКЖЕ
fnmatch(3), glob(3)