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

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

СИНТАКСИС
#include

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,
объявленным в и содержащим следующие элементы,
определенные в 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.