Linux repositories inspector
GNU
2019-03-06
Aliases: globfree(3), globfree(3), globfree(3), globfree(3), globfree(3), globfree(3), globfree(3), globfree(3), globfree(3), globfree(3), globfree(3), globfree(3)

man-pages-ru

Russian man pages from the Linux Documentation Project

manpages-dev

Manual pages about using GNU/Linux for development

man-pages

Linux kernel and C library user-space interface documentation

ИМЯ

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() пытается продолжить работу не смотря на ошибки, читая все каталоги, которые может.
GLOB_MARK
Добавлять косую черту к каждому пути, который соответствует каталогу.
GLOB_NOSORT
Не сортировать возвращаемые имена. Это экономит процессорное время. По умолчанию имена сортируются.
GLOB_DOOFFS
Резервировать слоты pglob->gl_offs у начала списка строк в pglob->pathv. Зарезервированные слоты содержат указатели null.
GLOB_NOCHECK
Если не найдено совпадений по шаблону, возвращать в качестве результата заданный шаблон. По умолчанию при отсутствии совпадений glob() возвращает GLOB_NOMATCH.
GLOB_APPEND
Добавлять результаты вызова к вектору результатов, полученному от предыдущего вызова glob(). Не следует включать этот флаг при первом вызове glob().
GLOB_NOESCAPE
Не использовать символы обратной косой черты (\(aq\\(aq) в качестве экранирующего символа. Обычно, обратная косая черта может использоваться для экранирования следующего символа, таким образом предоставляя механизм для выключения специального значения метасимволов.
В 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
Выполнять расширения тильды. Если тильда (\(aq~\(aq) — единственный символ в шаблоне или после начальной тильды сразу указана косая черта (\(aq/\(aq), то вместо тильды подставляется домашний каталог вызывающего Если после начальной тильды указано имя пользователя (например, "~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(), поэтому мы используем 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.

ДЕФЕКТЫ

Функция glob() может завершиться с ошибкой из-за ошибок в используемых её функций: malloc(3) или opendir(3). Эти функции записывают коды своих ошибок в переменную errno.

ПРИМЕР

Пример использования приводится ниже, в нём имитируется набор строки
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]);
⇧ Top