glob()

Найти пути, соответствующие шаблону

Прототип:

#include <glob.h>
                                       
int glob( const char *pattern,
          int flags,
          int (*errfunc)( const char *epath,
                                     int error ),
          glob_t *pglob );

Аргументы:

pattern

Шаблон, который вы хотите сопоставить. Шаблон может включать следующие специальные символы:

*

соответствует любой строке любой длины

?

соответствует любому одиночному символу

[chars]

соответствует любому из символов, найденных в строке chars.

flags

Флаги, влияющие на поиск.

errfunc

Указатель на функцию, которую вызывает glob(), когда встречает каталог, который не может открыть или прочитать.

pglob

Указатель на структуру glob_t, где glob() может хранить найденные пути.

Необходимо создать структуру glob_t перед вызовом glob(). Функция glob() выделяет необходимые ресурсы для массива gl_pathv. Используйте globfree() для освобождения этих ресурсов.

Библиотека:

libc

Описание:

Функция glob() находит пути, соответствующие заданному шаблону.

Чтобы иметь доступ к пути, glob() должен иметь разрешение на поиск для каждого компонента пути, кроме последнего, и разрешение на чтение для каждого каталога каждого компонента имени файла шаблона, который содержит любой из специальных символов (*, ?, [ и ]).

Аргумент errfunc - это указатель на функцию-обработчик ошибок с прототипом:

int errfunc( const char *epath, int error );

Функция errfunc вызывается, когда glob() встречает каталог, который он не может открыть или прочитать. Аргументы функции:

epath

Указатель на путь, по которому произошел сбой.

error

Значение errno из-за сбоя. Аргумент ошибки может быть установлен на любое из значений, возвращаемых opendir(), readdir(), или stat().

Функция errfunc должна возвращать 0, если функция glob() должна продолжаться, или ненулевое значение, если функция glob() должна прекратить поиск.

Вы можете установить для errfunc значение NULL, чтобы игнорировать эти типы ошибок.

Аргумент flags может иметь любую комбинацию следующих битов:

GLOB_APPEND

Добавить найденные пути к именам из предыдущего вызова glob().

GLOB_DOOFFS

Использовать значение в pglob->gl_offs, чтобы указать, сколько NULL указателей нужно добавить в начало pglob->pathv. После вызова glob() pglob->pathv будет содержать NULL указатели pglob->gl_offs, за которыми следуют пути pglob->gl_pathc, за которыми следует NULL указатель. Это может быть полезно, если вы создаете команду, которая будет применяться к совпадающим файлам.

GLOB_ERR

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

GLOB_MARK

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

GLOB_NOCHECK

Если pattern не соответствует ни одному пути, вернуть только содержимое pattern.

GLOB_NOESCAPE

Отключить экранирование обратной косой черты в pattern.

GLOB_NOSORT

Не сортировать возвращенные пути; их порядок не будет определен. По умолчанию пути сортируются.

Следующие флаги являются расширениями BSD:

GLOB_PERIOD

Разрешить метасимволам соответствовать начальным точкам.

GLOB_MAGCHAR

Шаблон имеет globbing-символы.

GLOB_ALTDIRFUNC

Использовать альтернативно указанные функции каталога.

GLOB_BRACE

Раскрывать фигурные скобки так же, как это делает оболочка C.

GLOB_NOMAGIC

Аналогично GLOB_NOCHECK без магических символов (csh).

GLOB_TILDE

Раскрыть пути, содержащие тильду, из файла passwd.

GLOB_NO_DOTDIRS

Удалить . и .. из специальных символов.

GLOB_LIMIT

Ограничить память, используемую совпадениями, до ARG_MAX.

Возвращаемое значение:

0 в случае успешного завершения, или код ошибки.

Коды ошибок:

GLOB_ABEND

Поиск был остановлен, поскольку был установлен флаг GLOB_ERR или функция errfunc вернула ненулевое значение.

GLOB_NOMATCH

Значение pattern не соответствует ни одному существующему пути, и флаг GLOB_NOCHECK не был установлен в flags.

GLOB_NOSPACE

Невозможно выделить память для хранения найденных путей.

Примеры:

Простой пример для поиска всех файлов с расширением .c в текущей директории и вывода их в том порядке, в котором их нашла файловая система.

#include <unistd.h>
#include <stdio.h>
#include <glob.h>
                                       
int main( void )
{
    glob_t  paths;
    int     retval;
        
    paths.gl_pathc = 0;
    paths.gl_pathv = NULL;
    paths.gl_offs  = 0;
                                       
    retval = glob( "*.c", GLOB_NOCHECK | GLOB_NOSORT, NULL, &paths );
    if( retval == 0 )
    {
        int idx;
            
        for ( idx = 0; idx < paths.gl_pathc; idx++ )
        {
            printf( "[%d]: %s\n", idx, paths.gl_pathv[idx] );
        }
            
        globfree( &paths );
    } else {
        puts( "glob() failed" );
    }
        
    return (0);
}

Классификация:

POSIX 1003.1

Безопасность использования

Точка остановки потока

Да

Обработчик прерываний

Нет

Обработчик сигналов

Да

В потоке

Да

Предостережения:

Не изменйяте значения в pglob между вызовами glob() и globfree().

Тематические ссылки:

glob_t, globfree(), wordexp(), wordfree()

Предыдущий раздел: Описание API системной библиотеки