glob (7) ( Русские man: Макропакеты и соглашения )
НАЗВАНИЕ
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()
может выдать сообщение об ошибке из-за ошибок связанных с ней функций, таких, как:
malloc() или opendir().
Эти функции сохраняют коды своих ошибок в переменной
errno.
ЗАМЕЧАНИЯ
Элементы структуры
gl_pathc
и
gl_offs
указаны как
size_t
в glibc 2.1 (как и должны указываться, согласно стандарту POSIX.2),
но указываются как
int
в libc4, libc5 и glibc 2.0.
