Man:Man3/regcomp.3
Матеріал з docs.linux.org.ua — збірника документації з Unix/Linux українською мовою.
НАЗВА
regcomp, regexec, regerror, regfree - функції регулярних виразів POSIX
СТИСЛИЙ ОГЛЯД
#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 - покажчик на область буферу, де компільований шаблон буде збережено, regex - покажчик на ланцюжок з нульовим закінченням і cflags - прапорцi, використовувані для визначення типу компіляції.
Усі пошуки регулярних виразів повинні виконуватись через компільований буферний шаблон, тож regexec завжди отримуватиме адресу буферу, у якому знаходиться бінарний шаблон, компільований regcomp.
cflags може бути порозрядним АБО одного або декількох з наступного:
- REG_EXTENDED
- Використовувати синтаксис розширених регулярних виразів POSIX під час інтерпретації regex. Якщо цей прапор не включено, то використовується синтаксис простих регулярних виразів POSIX.
- REG_ІCASE
- Не враховувати регістру літер. Наступні пошуки regexec з використанням шаблона у буфері не будуть залежати від регістру.
- REG_NOSUB
- Не вимагати підтримки адресації до частин ланцюжків всередині збігів. Параметри nmatch і pmatch для regexec ігноруються, якщо даний буферний шаблон був скомпільований з цим прапором.
- REG_NEWLІNE
- Оператори, що збігаються з будь-якими символами не співпадатимусть з новим рядком, тим не менш.
Негативний список ([^...]), у якому не вказано знаку нового рядка, не збігатиметься автоматично з новим рядком.
Оператори початку рядків (^) співпадатимуть з порожнім ланцюжком одразу після знаку нового рядка незалежно від того, чи eflags, прапор виконання regexec, містить REG_NOTBOL.
Оператор кінця рядка ($) збігатиметься з порожнім ланцюжком перед перед самим символом нового рядка, незалежно від того, чи eflags містить REG_NOTEOL.
СПІВПАДАННЯ З РЕГУЛЯРНИМИ ВИРАЗАМИ POSIX
regexec використовується для порівнювання ланцюжків з нульовим закінченням із попередньо-обробленим буферним шаблоном preg. Змінні nmatch та pmatch використовуються щоб отримати інформацію про місцезнаходження будь-яких збігів. eflags може бути порозрядним АБО одного або обох REG_NOTBOL і REG_NOTEOL. Ці значення визначають поведінку процесу порівнювання, як описано нижче.
- REG_NOTBOL
- Оператор початку нового рядка завжди зазнає навдачі (але дивіться, описаний вище, прапор обробки REG_NEWLІNE). Цей прапор може використовуватись, коли у regexec обробляються окремі частини ланцюжків, і початок таких частин, у даному випадку, не повинен розглядатись як початок нового рядка.
- REG_NOTEOL
- Не береться до уваги оператор кінця рядка (але дивіться, описаний вище, прапор обробки REG_NEWLІNE).
ПОЗИЦІЯ БАЙТІВ
Хіба REG_NOSUB було встановлено для обробки буферного шаблону, завжди є можливість отримати інформацію про положення внутрішньо-ланцюжкових збігів. pmatch повинно бути визначена так, щоб мати, принаймні, nmatch елементів. Вони заповнюються regexec-адресами внутрішньо-ланцюжкових збігів. Будь-які невикористані елементи структури будуть містити значення -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_sіze. Буде повернуто розмір errbuf, необхідного для утримування рядка з нульовим закінченням, містячого повідомленням про помилку. Якщо errbuf і errbuf_sіze не є нульовими, то errbuf заповнюється першими errbuf_sіze - 1 символами повідомлення про помилку і завершуються нулем.
ВИВІЛЬНЕННЯ БУФЕРУ ШАБЛОНУ ВІДПОВІДНО З POSIX
Після надання regfree попередньо обробленого буферного шаблону, preg звільнить пам'ять, відведену цьому шаблонові під час процесу компіляції regcomp.
ПОВЕРНЕНЕ ЗНАЧЕННЯ
regcomp повертає нуль при успішній компіляції або код помилки у випадку невдачі.
regexec повертає нуль у випадку співпадань або REG_NOMATCH, якщо співпадань не відбулося.
КОДИ ПОМИЛОК
regcomp може повертати наступні помилки:
- REG_BADRPT
- Невірне використання операторів повторення, наприклад '*' як перший символ.
- REG_BADBR
- Невірне використання операторів зворотних посилань.
- REG_EBRACE
- Відсутня пара фігурної дужки.
- REG_EBRACK
- Відсутня пара квадратної дужки (оператори списку).
- REG_ERANGE
- Невірне використання операторів інтервалу: у цьому випадку кінець інтервалу з'являється до його початку.
- REG_ECTYPE
- Невідома назва класу символів.
- REG_ECOLLATE
- Невірний елемент сортування, помилка сортування елементів.
- REG_EPAREN
- Відсутня пара круглої дужки (оператор групування).
- REG_ESUBREG
- Помилкове зворотнє посилання на частину виразу.
- REG_EEND
- Невизначена помилка. (Не описана у POSIX.2.)
- REG_EESCAPE
- Кінцевий зворотній слеш.
- REG_BADPAT
- Невірне використання операторів шаблону, таких як оператори групи або списку.
- REG_ESІZE
- Компільований регулярний вираз вимагає буферний шаблон розміром більшим за 64 Кб. (Не описано у POSIX.2.)
- REG_ESPACE
- Виснаження пам'яті функціями регулярних виразів.
ВІДПОВІДНІСТЬ СТАНДАРТАМ
POSIX.2
ДИВІТЬСЯ ТАКОЖ
regex(7), GNU regex manual
Переклав українською Віталій Цибуляк <vi@uatech.atspace.com>
