Linux Man на русском

  User    Syst    Libr    Device    Files    Other    Admin  



   regexec - функции регулярных выражений POSIX

regexec(3) функции регулярных выражений POSIX

Other Alias

regcomp, regerror, regfree


ОБЗОР

#include <sys/types.h>
#include <regex.h>
int regcomp(regex_t *preg, const char *regex, int cflags);
int regexec(const regex_t *preg, const char *string, size_t nmatch,
regmatch_t pmatch[], int eflags);
size_t regerror(int errcode, const regex_t *preg, char *errbuf,
size_t errbuf_size);
void regfree(regex_t *preg);


ОПИСАНИЕ

Компилирование регулярных выражений POSIX

Функция regcomp() используется для компиляции регулярного выражения в формат, который подходит для последующих поисков с помощью regexec().

regcomp() передаётся указатель на область хранения буферного шаблона preg, указатель на заканчивающуюся null строку regex и флаги cflags, используемые для определения типа компиляции.

Все поиски регулярных выражений должны выполняться с помощью скомпилированного буферного шаблона, поэтому regexec() должна всегда вызываться с адресом буферного шаблона, инициализированного функцией regcomp().

Значение cflags может состоять из поразрядного or нуля или нескольких следующих значений:

REG_EXTENDED Использовать синтаксис расширенных регулярных выражений POSIX во время интерпретации regex. Если не включён этот флаг, то используется синтаксис простых регулярных выражений POSIX.

REG_ICASE Не учитывать регистр. Последующие поиски regexec() с использованием данного буферного шаблона не будут зависеть от регистра.

REG_NOSUB Не сообщать положение совпадений. Параметры nmatch и pmatch для regexec() игнорируются, если данный буферный шаблон был скомпилирован с этим включённым флагом.

REG_NEWLINE Операторы совпадения с любым символом не совпадают с символом новой строки.

Список несовпадающих символов ([^...]) без символа новой строки не совпадает с новой строкой.

Оператор сравнения по началу строки (^) совпадает с пустой строкой сразу после новой строки независимо от того, что eflags, флаги выполнения regexec(), содержат REG_NOTBOL.

Оператор сравнения по концу строки ($) совпадает с пустой строкой до символа начала строки независимо от того, что eflags содержит REG_NOTEOL.

Сравнение с регулярным выражением POSIX

Функция regexec() используется для сравнения строки, завершающейся null, с предварительно обработанным буферным шаблоном preg. Аргументы nmatch и pmatch используются для предоставления информации о местонахождении любых совпадений. Значение eflags может быть поразрядным ИЛИ одного или обоих значений REG_NOTBOL и REG_NOTEOL. Данные значения определяют поведение процесса сравнения так, как описано ниже.

REG_NOTBOL Оператор сравнения по началу строки всегда завершается с ошибкой (но смотрите описанный выше флаг компиляции REG_NEWLINE). Этот флаг может использоваться, когда в regexec() передаются отдельные части строки, и начало такой строки в данном случае не должно интерпретироваться как начало новой строки.

REG_NOTEOL Оператор сравнения по концу строки всегда завершается с ошибкой (но смотрите описанный выше флаг компиляции REG_NEWLINE).

Байтовые смещения

Если REG_NOSUB не установлен при компиляции буферного шаблона, то возможно получать информацию о положении совпадений. Значение pmatch должно быть определено так, чтобы иметь, по крайней мере, nmatch элементов. Они заполняются regexec() адресами внутристрочных совпадений. Смещения подвыражения, начинающегося с i-й открытой скобки, сохраняется в pmatch[i]. Адрес совпадения всего регулярного выражения сохраняется в pmatch[0] (заметим, что чтобы вернуть смещения совпадений N подвыражений, значение nmatch должно быть не менее N+1). Любые неиспользованные элементы структуры будут содержать значение -1.

Структура regmatch_t, являющаяся типом pmatch, определена в <regex.h>:

typedef struct {
    regoff_t rm_so;
    regoff_t rm_eo;
} regmatch_t;

Каждый элемент rm_so, не равный -1, показывает начальное смещение следующего совпадения наибольшей подстроки внутри заданной строки. Относительный элемент rm_eo указывает на смещение конца совпадения, которое является первым символом после совпавшего текста.

Сообщение об ошибках POSIX

Функция regerror используется для преобразования кодов ошибок, которые могут быть получены от regcomp() и regexec(), в строки сообщений об ошибках.

В regerror передаются: код ошибки errcode, буферный шаблон preg, указатель на символьный буфер строки errbuf и размер буфера строки errbuf_size. Функция возвращает размер errbuf, который требуется для сохранения сообщения об ошибке в виде строки, оканчивающейся null. Если и errbuf, и errbuf_size не равны нулю, то errbuf заполняется первыми errbuf_size - 1 символами сообщения об ошибке и завершается байтом null ('\0').

Освобождение буфера шаблона POSIX

Функция regfree() освобождает память, отведённую буферному шаблону preg во время процесса компиляции с помощью regcomp().


ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

Функция regcomp() возвращает ноль при успешной компиляции или в противном случае код ошибки.

Функция regexec() возвращает ноль при совпадении или REG_NOMATCH, если совпадений не было.


ОШИБКИ

Функция regcomp() может возвращать следующие ошибки:

REG_BADBR Неправильное использование оператора обратных ссылок.

REG_BADPAT Неправильное использование операторов шаблона, таких, как операторы группы или списка.

REG_BADRPT Неправильное использование операторов повторения, например, использование «*» в качестве первого символа.

REG_EBRACE Непарные скобки в операторах интервала.

REG_EBRACK Непарные квадратные скобки в операторах списка.

REG_ECOLLATE Неправильный элемент сортировки.

REG_ECTYPE Неизвестное имя класса символов.

REG_EEND Потенциальная ошибка. Не определена в POSIX.2.

REG_EESCAPE Конечная обратная косая черта.

REG_EPAREN Непарные круглые скобки в операторах группировки.

REG_ERANGE Неправильное использование оператора области: например, конец области появляется прежде её начала.

REG_ESIZE Скомпилированное регулярное выражение требует буферный шаблон размером, большим 64 Кб. Это не определено в POSIX.2.

REG_ESPACE Для процедур регулярных выражений закончилась память.

REG_ESUBREG Неправильная обратная ссылка на подвыражение.


АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).

Интерфейс Атрибут Значение
regcomp(), regexec() безвредность в потоках: безвредно (MT-Safe locale)
regerror() безвредность в потоках: безвредно (MT-Safe env)
regfree() безвредность в потоках: безвредно (MT-Safe)


СООТВЕТСТВИЕ СТАНДАРТАМ

POSIX.1-2001, POSIX.1-2008.