| regex(3) | Library Functions Manual | regex(3) |
الاسم¶
regcomp, regexec, regerror, regfree - دوال التعبير النمطي POSIX
المكتبة¶
مكتبة سي المعيارية (libc، -lc)
موجز¶
#include <regex.h>
int regcomp(regex_t *restrict preg, const char *restrict regex,
int cflags);
int regexec(const regex_t *restrict preg,
const char *restrict string,
size_t n, regmatch_t pmatch[_Nullable restrict n],
int eflags);
size_t regerror(size_t errbuf_size;
int errcode, const regex_t *_Nullable restrict preg,
char errbuf[_Nullable restrict errbuf_size],
size_t errbuf_size);
void regfree(regex_t *preg);
typedef struct {
size_t re_nsub;
} regex_t;
typedef struct {
regoff_t rm_so;
regoff_t rm_eo;
} regmatch_t;
typedef /* ... */ regoff_t;
الوصف¶
التجميع¶
تُستخدم regcomp() لتجميع تعبير نمطي إلى صيغة مناسبة لعمليات بحث regexec() لاحقة.
عند النجاح، يُهيأ مخبأ النمط عند *preg. regex هي سلسلة محارف منتهية بقيمة خالية. يجب أن يكون الإعداد المحلي نفسه عند تشغيل regexec().
بعد نجاح regcomp() ، يحمل preg->re_nsub عدد التعبيرات الفرعية في regex. لذا، فإن قيمة preg->re_nsub + 1 الممررة كـ n إلى regexec() كافية لالتقاط جميع التطابقات.
cflags هو OR على مستوى البتات لصفر أو أكثر مما يلي:
- REG_EXTENDED
- استخدم صيغة التعبير النمطي الموسع POSIX عند تفسير regex. إذا لم يُضبط، تُستخدم صيغة التعبير النمطي الأساسي POSIX.
- REG_ICASE
- لا تفرق بين حالة الأحرف. ستكون عمليات بحث regexec() اللاحقة باستخدام مخبأ النمط هذا غير حساسة لحالة الأحرف.
- REG_NOSUB
- أبلغ فقط عن النجاح الكلي. ستستخدم regexec() فقط pmatch لـ REG_STARTEND، متجاهلة n.
- REG_NEWLINE
- لا تطابق عوامل تشغيل تطابق أي حرف سطرًا جديدًا.
- قائمة غير مطابقة ([^...]) لا تحتوي على سطر جديد لا تطابق سطرًا جديدًا.
- عامل مطابقة بداية السطر (^) يطابق السلسلة الفارغة فورًا بعد سطر جديد، بغض النظر عن احتواء eflags، أعلام تنفيذ regexec()، على REG_NOTBOL.
- عامل مطابقة نهاية السطر ($) يطابق السلسلة الفارغة فورًا قبل سطر جديد، بغض النظر عن احتواء eflags على REG_NOTEOL.
المطابقة¶
تُستخدم regexec() لمطابقة سلسلة محارف منتهية بقيمة فارغة مع مخبأ النمط المُجمَّع في *preg، الذي يجب أن يكون قد تمت تهيئته باستخدام regcomp(). eflags هو OR على مستوى البت لصفر أو أكثر من الأعلام التالية:
- REG_NOTBOL
- عامل مطابقة بداية السطر يفشل دائمًا في المطابقة (لكن انظر علم التجميع REG_NEWLINE أعلاه). يمكن استخدام هذا العلم عندما تُمرَّر أجزاء مختلفة من سلسلة محارف إلى regexec() ولا ينبغي تفسير بداية السلسلة على أنها بداية السطر.
- REG_NOTEOL
- عامل مطابقة نهاية السطر يفشل دائمًا في المطابقة (لكن انظر علم التجميع REG_NEWLINE أعلاه).
- REG_STARTEND
- يطابق [string + pmatch[0].rm_so, string + pmatch[0].rm_eo) بدلاً من [string, strnul(string)). يسمح هذا بمطابقة وحدات البايت NUL المُضمَّنة. إذا تم إرجاع أي مطابقات (لم يُمرَّر REG_NOSUB إلى regcomp()، نجحت المطابقة، و n > 0)، فإنها تستبدل pmatch كالمعتاد، وتبقى إزاحات المطابقة نسبة إلى string (وليس string + pmatch[0].rm_so). هذا العلم هو امتداد BSD، غير موجود في POSIX.
إزاحات المطابقة¶
ما لم يُمرَّر REG_NOSUB إلى regcomp()، يمكن الحصول على مواقع المطابقات داخل string: تملأ regexec() عناصر n من pmatch بالنتائج: يتوافق pmatch[0] مع المطابقة بأكملها، و pmatch[1] مع أول تعبير فرعي، وهكذا. إذا كان هناك مطابقات أكثر من n، يتم التخلص منها؛ إذا كان أقل، تُملأ العناصر غير المستخدمة من pmatch بقيم -1.
كل مطابقة صالحة مُعادة (غير -1) تتوافق مع النطاق [string + rm_so, string + rm_eo).
regoff_t هو نوع عدد صحيح مُوقَّع قادر على تخزين أكبر قيمة يمكن تخزينها إما في نوع ptrdiff_t أو نوع ssize_t.
الإبلاغ عن الأخطاء¶
تُستخدم regerror() لتحويل رموز الخطأ التي يمكن إرجاعها بواسطة كل من regcomp() و regexec() إلى سلاسل محارف لرسائل الخطأ.
إذا لم يكن preg مؤشرًا فارغًا، يجب أن يكون errcode أحدث خطأ تم إرجاعه من عملية على preg.
إذا لم يكن errbuf_size 0، يتم نسخ ما يصل إلى errbuf_size بايت إلى errbuf؛ سلسلة محارف الخطأ تكون دائمًا منتهية بقيمة فارغة، ومُقتطعة لتناسب.
التحرير¶
regfree() تُنهي تهيئة مخزن النمط عند *preg، مُحررةً أي ذاكرة مرتبطة؛ يجب أن يكون *preg قد هُيئ عبر regcomp().
قيمة الإرجاع¶
regcomp() تُرجع صفرًا عند التجميع الناجح أو رمز خطأ عند الفشل.
regexec() تُرجع صفرًا عند المطابقة الناجحة أو REG_NOMATCH عند الفشل.
regerror() تُرجع حجم المخزن المطلوب لاحتواء سلسلة المحارف.
الأخطاء¶
يمكن إرجاع الأخطاء التالية بواسطة regcomp():
- REG_BADBR
- استخدام غير صحيح لعامل المرجع الخلفي.
- REG_BADPAT
- استخدام غير صحيح لعوامل النمط مثل المجموعة أو القائمة.
- REG_BADRPT
- استخدام غير صحيح لعوامل التكرار مثل استخدام '*' كأول محرف.
- REG_EBRACE
- عوامل نطاق الأقواس غير المتطابقة.
- REG_EBRACK
- عوامل قائمة الأقواس غير المتطابقة.
- REG_ECOLLATE
- عنصر ترتيب غير صحيح.
- REG_ECTYPE
- اسم فئة محارف غير معروف.
- REG_EEND
- خطأ غير محدد. هذا غير مُعرَّف بواسطة POSIX.
- REG_EESCAPE
- شرطة مائلة عكسية زائدة.
- REG_EPAREN
- عوامل مجموعة الأقواس غير المتطابقة.
- REG_ERANGE
- استخدام غير صحيح لعامل النطاق؛ على سبيل المثال، تحدث نقطة نهاية النطاق قبل نقطة البداية.
- REG_ESIZE
- يتطلب التعبير النمطي المُجمَّع مخزن نمط أكبر من 64 كيلوبايت. هذا غير مُعرَّف بواسطة POSIX.
- REG_ESPACE
- نفدت الذاكرة من روتينات regex.
- REG_ESUBREG
- مرجع خلفي غير صحيح لتعبير فرعي.
السمات¶
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
| الواجهة | السمة | القيمة |
| regcomp(), regexec() | سلامة الخيوط | المنطقة (locale) آمنة لتعدد المسالك (MT-Safe) |
| regerror() | سلامة الخيوط | بيئة آمنة لتعدد الخيوط (MT-Safe) |
| regfree() | سلامة الخيوط | MT-Safe |
المعايير¶
POSIX.1-2008.
التاريخ¶
POSIX.1-2001.
قبل POSIX.1-2008، كان مطلوبًا من regoff_t أن يكون قادرًا على تخزين أكبر قيمة يمكن تخزينها في نوع off_t أو نوع ssize_t.
تحذيرات¶
re_nsub مطلوب فقط أن يُهيَّأ إذا لم يُحدد REG_NOSUB، لكن جميع التطبيقات المعروفة تُهيِّئه بغض النظر.
قد يحتوي كل من regex_t و regmatch_t على أعضاء إضافيين (ويفعلون ذلك)، بأي ترتيب. ارجع إليهم دائمًا بالاسم.
أمثلة¶
#include <stdcountof.h> #include <stdint.h> #include <stdio.h> #include <stdlib.h> #include <regex.h> static const char *const str =
"1) John Driverhacker;\n2) John Doe;\n3) John Foo;\n"; static const char *const re = "John.*o"; int main(void) {
static const char *s = str;
regex_t regex;
regmatch_t pmatch[1];
regoff_t off, len;
if (regcomp(®ex, re, REG_NEWLINE))
exit(EXIT_FAILURE);
printf("String = \"%s\"\n", str);
printf("Matches:\n");
for (unsigned int i = 0; ; i++) {
if (regexec(®ex, s, countof(pmatch), pmatch, 0))
break;
off = pmatch[0].rm_so + (s - str);
len = pmatch[0].rm_eo - pmatch[0].rm_so;
printf("#%u:\n", i);
printf("offset = %jd; length = %jd\n", (intmax_t) off,
(intmax_t) len);
printf("substring = \"%.*s\"\n", len, s + pmatch[0].rm_so);
s += pmatch[0].rm_eo;
}
exit(EXIT_SUCCESS); }
انظر أيضًا¶
قسم دليل glibc، التعبيرات النمطية
ترجمة¶
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>
هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.
إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.
| 22 فبراير 2026 | صفحات دليل لينكس (لم تصدر بعد) |