GLOB(3)

НАЗВАНИЕ
glob, globfree - поиск имен файлов по заданному шаблону, освобождение памяти от результатов работы функции glob()

СИНТАКСИС
#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_MARK
    - добавлять косую черту к каждому пути, соответствующему каталогу;

GLOB_NOSORT
    - не сортировать найденные имена (по умолчанию они сортируются);

GLOB_DOOFFS
    - место для pglob->gl_offs будет зарезервировано в начале списка строк, в pglob->pathv;

GLOB_NOCHECK
    - если не найдено совпадений по шаблону, то возвращать в качестве результата заданный шаблон;

GLOB_APPEND
    - добавлять найденные результаты к предыдущим результатам (не следует включать этот флаг при первом вызове glob());

GLOB_NOESCAPE
    - метасимволы не могут быть ограничены символами обратной косой черты.

Используемые флаги могут быть дополнены следующими флагами (являющимися расширениями 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));

GLOB_NOMAGIC
    (возвращается сам шаблон, если в нем не содержатся метасимволы);

GLOB_TILDE
    (поддерживаются расширения тильды);

GLOB_ONLYDIR
    (ведется поиск только каталогов);

Если errfunc не равно NULL, то оно будет вызвано в случае ошибок с параметрами epath (указатель пути, в котором произошла ошибка) и eerrno. Значение errno возвращается после вызова одной из функций: opendir(), readdir() или stat(). Если 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
    (не найдено никаких совпадений с шаблоном).

ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ
Один пример использования приводится ниже, в нем эмулируется набор строки 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]);

СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.2

НАЙДЕННЫЕ ОШИБКИ
Функция glob() может выдать сообщение об ошибке из-за ошибок связанных с ней функций, таких, как: malloc() или opendir(). Эти функции сохраняют коды своих ошибок в переменной errno.

ЗАМЕЧАНИЯ
Элементы структуры gl_pathc и gl_offs указаны как size_t в glibc 2.1 (как и должны указываться, согласно стандарту POSIX.2), но указываются как int в libc4, libc5 и glibc 2.0.

СМ. ТАКЖЕ
ls(1), sh(1), stat(2), exec(3), malloc(3), opendir(3), readdir(3), wordexp(3), glob(7)