Scroll to navigation

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 على مستوى البتات لصفر أو أكثر مما يلي:

استخدم صيغة التعبير النمطي الموسع POSIX عند تفسير regex. إذا لم يُضبط، تُستخدم صيغة التعبير النمطي الأساسي POSIX.
لا تفرق بين حالة الأحرف. ستكون عمليات بحث regexec() اللاحقة باستخدام مخبأ النمط هذا غير حساسة لحالة الأحرف.
أبلغ فقط عن النجاح الكلي. ستستخدم regexec() فقط pmatch لـ REG_STARTEND، متجاهلة n.
لا تطابق عوامل تشغيل تطابق أي حرف سطرًا جديدًا.
قائمة غير مطابقة ([^...]) لا تحتوي على سطر جديد لا تطابق سطرًا جديدًا.
عامل مطابقة بداية السطر (^) يطابق السلسلة الفارغة فورًا بعد سطر جديد، بغض النظر عن احتواء eflags، أعلام تنفيذ regexec()، على REG_NOTBOL.
عامل مطابقة نهاية السطر ($) يطابق السلسلة الفارغة فورًا قبل سطر جديد، بغض النظر عن احتواء eflags على REG_NOTEOL.

المطابقة

تُستخدم regexec() لمطابقة سلسلة محارف منتهية بقيمة فارغة مع مخبأ النمط المُجمَّع في *preg، الذي يجب أن يكون قد تمت تهيئته باستخدام regcomp(). eflags هو OR على مستوى البت لصفر أو أكثر من الأعلام التالية:

عامل مطابقة بداية السطر يفشل دائمًا في المطابقة (لكن انظر علم التجميع REG_NEWLINE أعلاه). يمكن استخدام هذا العلم عندما تُمرَّر أجزاء مختلفة من سلسلة محارف إلى regexec() ولا ينبغي تفسير بداية السلسلة على أنها بداية السطر.
عامل مطابقة نهاية السطر يفشل دائمًا في المطابقة (لكن انظر علم التجميع REG_NEWLINE أعلاه).
يطابق [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():

استخدام غير صحيح لعامل المرجع الخلفي.
استخدام غير صحيح لعوامل النمط مثل المجموعة أو القائمة.
استخدام غير صحيح لعوامل التكرار مثل استخدام '*' كأول محرف.
عوامل نطاق الأقواس غير المتطابقة.
عوامل قائمة الأقواس غير المتطابقة.
عنصر ترتيب غير صحيح.
اسم فئة محارف غير معروف.
خطأ غير محدد. هذا غير مُعرَّف بواسطة POSIX.
شرطة مائلة عكسية زائدة.
عوامل مجموعة الأقواس غير المتطابقة.
استخدام غير صحيح لعامل النطاق؛ على سبيل المثال، تحدث نقطة نهاية النطاق قبل نقطة البداية.
يتطلب التعبير النمطي المُجمَّع مخزن نمط أكبر من 64 كيلوبايت. هذا غير مُعرَّف بواسطة POSIX.
نفدت الذاكرة من روتينات regex.
مرجع خلفي غير صحيح لتعبير فرعي.

السمات

للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر 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(&regex, re, REG_NEWLINE))


        exit(EXIT_FAILURE);


    printf("String = \"%s\"\n", str);


    printf("Matches:\n");


    for (unsigned int i = 0; ; i++) {


        if (regexec(&regex, 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);
}

انظر أيضًا

grep(1), regex(7)

قسم دليل glibc، التعبيرات النمطية

ترجمة

تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.

22 فبراير 2026 صفحات دليل لينكس 6.18