ОБЗОР

#include <glob.h>

---

int glob(const char *pattern, int flags,
int (*errfunc) (const char *epath, int eerrno),
glob_t *pglob);
void globfree(glob_t *pglob);

ОПИСАНИЕ

Функция glob() ищет все совпадения имён путей с заданным шаблоном pattern, согласно правилам, используемым оболочкой (смотрите glob(7)). Расширения тильды или подстановка параметров не выполняется; если это нужно, то используйте wordexp(3).

Функция globfree() освобождает динамически выделенное хранилище, полученное в последнем вызове glob().

Результаты вызова glob() сохраняются в структуре, на которую указывает pglob. Эта структура имеет тип glob_t (объявлен в <glob.h>) и содержит следующие элементы, определённые в POSIX.2 (их может быть и больше, в виде расширений):

typedef struct {
    size_t   gl_pathc;    /* количество совпавших путей  */
    char   **gl_pathv;    /* список совпавших имён путей.  */
    size_t   gl_offs;     /* зарезервированные в gl_pathv слоты.  */
} glob_t;

Результаты размещаются в динамически выделяемом хранилище.

Значение параметра flags формируется побитовым сложением нуля или более следующих символических констант, которые меняют ход работы glob():

GLOB_ERR

Выполнять возврат при ошибке чтения (например, нет прав для чтения каталога). По умолчанию glob() пытается продолжить работу не смотря на ошибки, читая все каталоги, которые может.

GLOB_MARK

Добавлять косую черту к каждому пути, который соответствует каталогу.

GLOB_NOSORT

Не сортировать возвращаемые имена. Это экономит процессорное время. По умолчанию имена сортируются.

GLOB_DOOFFS

Резервировать слоты pglob->gl_offs у начала списка строк в pglob->pathv. Зарезервированные слоты содержат указатели null.

GLOB_NOCHECK

Если не найдено совпадений по шаблону, возвращать в качестве результата заданный шаблон. По умолчанию при отсутствии совпадений glob() возвращает GLOB_NOMATCH.

GLOB_APPEND

Добавлять результаты вызова к вектору результатов, полученному от предыдущего вызова glob(). Не следует включать этот флаг при первом вызове glob().

GLOB_NOESCAPE

Не использовать символы обратной косой черты ('\') в качестве экранирующего символа. Обычно, обратная косая черта может использоваться для экранирования следующего символа, таким образом предоставляя механизм для выключения специального значения метасимволов.

В flags также могу быть включены следующие флаги, которые являются расширениями GNU и отсутствуют в POSIX.2:

GLOB_PERIOD

Разрешить начальной точке соответствовать метасимволам. По умолчанию метасимволы не считаются совпадающими с начальной точкой.

GLOB_ALTDIRFUNC

Для доступа к файловой системе использовать функции pglob->gl_closedir, pglob->gl_readdir, pglob->gl_opendir, pglob->gl_lstat и pglob->gl_stat вместо стандартных библиотечных функций.

GLOB_BRACE

Раскрывать выражения в фигурных скобках {a,b} аналогичны используемым в csh(1). Выражения могут быть вложенными. То есть, например, по шаблону "{foo/{,cat,dog},bar}" возвращаются те же результаты что и при четырёх отдельных вызовах glob() со строками: "foo/", "foo/cat", "foo/dog" и "bar".

GLOB_NOMAGIC

Возвращать сам шаблон, если в нём не содержатся метасимволы, даже при отсутствии файла с таким именем.

GLOB_TILDE

Выполнять расширения тильды. Если тильда ('~') — единственный символ в шаблоне или после начальной тильды сразу указана косая черта ('/'), то вместо тильды подставляется домашний каталог вызывающего Если после начальной тильды указано имя пользователя (например, "~andrea/bin"), то вместо тильды и имени пользователя подставляется домашний каталог этого пользователя. Если имя пользователя некорректно или домашний каталог невозможно определить, то подстановка не выполняется.

GLOB_TILDE_CHECK

Поведение подобно GLOB_TILDE. Отличие в том, что если имя пользователя некорректно или домашний каталог невозможно определить, то вместо использования самого шаблона как имени, glob() возвращает GLOB_NOMATCH для указания на ошибку.

GLOB_ONLYDIR

Это только указание glob() на то, что вызывающего интересуют только каталоги, соответствующие шаблону. Если реализация может легко определить информацию о типе файла, то файлы не каталоги не возвращаются вызывающему. Однако, вызывающий всё равно должен проверять, что полученные файлы — каталоги (назначение этого флага — все лишь оптимизация производительности в случае, когда вызывающему нужны только каталоги).

Если errfunc не равно NULL, то в случае ошибки она будет вызвана с параметрами epath (указатель на путь, в котором произошла ошибка) и eerrno (полученное значение errno после вызова одной из функций opendir(3), readdir(3) или stat(2)).Если errfunc вернёт ненулевое значение или если флаг GLOB_ERR установлен, то glob() закончит работу после вызова errfunc.

При успешном выполнении в pglob->gl_pathc содержится количество совпадающих имён, а pglob->gl_pathv содержит указатель на список указателей на найденные имена. Список указателей завершается указателем null.

Вызов glob() может выполняться несколько раз. В этом случае флаг GLOB_APPEND должен быть включён в flags при втором и последующих вызовах.

Как расширение GNU, при обнаружении метасимволов pglob->gl_flags — набор задаваемых флагов, сложенный с GLOB_MAGCHAR (с помощью операции ИЛИ).

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

При успешном выполнении glob() возвращает ноль. Другие возможные возвращаемые значения:

GLOB_NOSPACE

занята вся свободная память

GLOB_ABORTED

ошибка чтения

GLOB_NOMATCH

не найдено совпадений с шаблоном

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).

Интерфейс	Атрибут	Значение
glob()	безвредность в нитях	MT-Unsafe race:utent env sig:ALRM timer locale
globfree()	безвредность в нитях	безвредно (MT-Safe)

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

СООТВЕТСТВИЕ СТАНДАРТАМ

POSIX.1-2001, POSIX.1-2008, POSIX.2.

ЗАМЕЧАНИЯ

Элементы структуры gl_pathc и gl_offs объявлены с типом size_t в glibc 2.1 (как и должны указываться, согласно POSIX.2), но указаны как int в glibc 2.0.

ПРИМЕР

Пример использования приводится ниже, в нём имитируется набор строки

ls -l *.c ../*.c

в оболочке:

glob_t globbuf;
globbuf.gl_offs = 2;
glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf);
globbuf.gl_pathv[0] = "ls";
globbuf.gl_pathv[1] = "-l";
execvp("ls", &globbuf.gl_pathv[0]);