الاسم

مكتبة سي المعيارية (libc، -lc)

#include <glob.h>

int glob(const char *restrict pattern, int flags,
         typeof(int (const char *epath, int eerrno)) *errfunc,
         glob_t *restrict pglob);
void globfree(glob_t *pglob);

الدالة glob() تبحث عن جميع أسماء المسارات المطابقة لـ pattern وفقًا للقواعد المستخدمة من قبل الصدفة (انظر glob(7)). لا يتم توسيع التلدة أو استبدال المعامل؛ إذا أردت هذه، استخدم wordexp(3).

الدالة globfree() تحرر التخزين المخصص ديناميكيًا من استدعاء سابق لـ glob().

نتائج استدعاء glob() تُخزن في البنية المشار إليها بواسطة pglob. هذه البنية من النوع glob_t (مُعلنة في <glob.h>) وتتضمن العناصر التالية المُعرفة بواسطة POSIX.2 (قد يكون هناك المزيد كإضافة):

typedef struct {
    size_t   gl_pathc;    /* عدد المسارات المطابقة حتى الآن  */
    char   **gl_pathv;    /* قائمة أسماء المسارات المطابقة.  */
    size_t   gl_offs;     /* فتحات للحجز في gl_pathv.  */
} glob_t;

النتائج تُخزن في تخزين مخصص ديناميكيًا.

المعامل flags يتكون من OR على مستوى البت لصفر أو أكثر من الثوابت الرمزية التالية، والتي تُعدل سلوك glob():

GLOB_ERR

الإرجاع عند خطأ قراءة (لأن دليلاً ليس لديه إذن قراءة، على سبيل المثال). مبدئيًا، glob() تحاول الاستمرار رغم الأخطاء، قارئةً جميع الأدلة التي تستطيع.

GLOB_MARK

إلحاق شرطة مائلة لكل مسار يتوافق مع دليل.

GLOB_NOSORT

لا تُرتب أسماء المسارات المُرجعة. السبب الوحيد لفعل ذلك هو توفير وقت المعالجة. مبدئيًا، أسماء المسارات المُرجعة تُرتب.

GLOB_DOOFFS

حجز pglob->gl_offs فتحة في بداية قائمة السلاسل المحارف في pglob->pathv. الفتحات المحجوزة تحتوي على مؤشرات فارغة.

GLOB_NOCHECK

إذا لم يطابق أي نمط، إرجاع النمط الأصلي. مبدئيًا، glob() تُرجع GLOB_NOMATCH إذا لم تكن هناك مطابقات.

GLOB_APPEND

ألحق نتائج هذه الاستدعاء بمتجه النتائج التي أرجعها استدعاء سابق للدالة glob(). لا تضبط هذه العلامة في أول استدعاء للدالة glob().

GLOB_NOESCAPE

لا تسمح باستخدام الخط المائل العكسي ('\') كمحرف هروب. عادة، يُستخدم الخط المائل العكسي لعزل المحرف التالي، مما يوفر آلية لإيقاف المعنى الخاص للمحارف الوصفية.

قد تتضمن flags أيضًا أيًا مما يلي، وهي إضافات GNU ولم تُعرف في POSIX.2:

GLOB_PERIOD

اسمح للمحارف الوصفية بمطابقة النقطة البادئة. مبدئيًا، لا يمكن للمحارف الوصفية مطابقة النقطة البادئة.

GLOB_ALTDIRFUNC

استخدم دوالًا بديلة pglob->gl_closedir وpglob->gl_readdir وpglob->gl_opendir وpglob->gl_lstat وpglob->gl_stat للوصول إلى نظام الملفات بدلًا من دوال المكتبة العادية.

GLOB_BRACE

وسّع تعابير الأقواس المعقوفة بنمط csh(1) من الشكل {a,b}. يمكن تتداخل تعابير الأقواس المعقوفة. وهكذا، على سبيل المثال، تحديد النمط "{foo/{,cat,dog},bar}" سيعيد نفس نتائج أربع استدعاءات منفصلة للدالة glob() باستخدام السلاسل: "foo/" و"foo/cat" و"foo/dog" و"bar".

GLOB_NOMAGIC

إذا لم يحتوي النمط على محارف وصفية، فيجب إعادته كالكلمة المطابقة الوحيدة، حتى لو لم يوجد ملف بهذا الاسم.

GLOB_TILDE

نفّذ توسيع التلدة. إذا كانت التلدة ('~') هي المحرف الوحيد في النمط، أو تبعتها تلدة أولية مباشرة بشرطة مائلة ('/')، فسيُستبدل دليل المستخدم الرئيسي للمتصل بالتلدة. إذا تبعَت تلدة أولية اسم مستخدم (مثل "~andrea/bin")، فستُستبدل التلدة واسم المستخدم بدليل المستخدم الرئيسي لذلك المستخدم. إذا كان اسم المستخدم غير صالح، أو تعذر تحديد دليل المستخدم الرئيسي، فلن يُجرَ أي استبدال.

GLOB_TILDE_CHECK

يوفر هذا سلوكًا مشابهًا لسلوك GLOB_TILDE. الفرق هو أنه إذا كان اسم المستخدم غير صالح، أو تعذر تحديد دليل المستخدم الرئيسي، فبدلًا من استخدام النمط نفسه كاسم، تُرجع الدالة glob() القيمة GLOB_NOMATCH للإشارة إلى خطأ.

GLOB_ONLYDIR

هذا تلميح للدالة glob() بأن المتصل مهتم فقط بالأدلة التي تطابق النمط. إذا استطاع التنفيذ تحديد معلومات نوع الملف بسهولة، فلن تُعاد الملفات غير الدليلية إلى المتصل. ومع ذلك، يجب على المتصل التحقق من أن الملفات المُعادة هي أدلة. (الغرض من هذه العلامة هو فقط تحسين الأداء عندما يكون المتصل مهتمًا بالأدلة فقط.)

إذا لم تكن errfunc NULL، فستُستدعى في حالة حدوث خطأ مع المعاملات epath، مؤشر إلى المسار الذي فشل، وeerrno، قيمة errno كما أُعيدت من أحد استدعاءات opendir(3) أو readdir(3) أو stat(2). إذا أعادت errfunc قيمة غير صفرية، أو إذا ضُبطت GLOB_ERR، فستنتهي الدالة glob() بعد استدعاء errfunc.

عند الإرجاع الناجح، يحتوي pglob->gl_pathc على عدد أسماء المسارات المطابقة ويحتوي pglob->gl_pathv على مؤشر إلى قائمة المؤشرات لأسماء المسارات المطابقة. تُنهى قائمة المؤشرات بمؤشر فارغ.

من الممكن استدعاء glob() عدة مرات. في هذه الحالة، يجب تعيين العلم GLOB_APPEND في flags في الاستدعاءات الثانية واللاحقة.

كإضافة لـ GNU، تُعيّن pglob->gl_flags إلى الأعلام المحددة، مع إجراء عملية أو مع GLOB_MAGCHAR إذا وُجدت أي محارف وصفية.

عند الإكمال بنجاح، تُرجع glob() صفرًا. القيم الأخرى الممكنة للإرجاع هي:

GLOB_NOSPACE

لنفاد الذاكرة،

GLOB_ABORTED

لخطأ في القراءة، و

GLOB_NOMATCH

لعدم وجود تطابقات.

للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).

في الجدول أعلاه، يشير utent في race:utent إلى أنه إذا استُخدمت أي من الدوال setutent(3) أو getutent(3) أو endutent(3) بالتوازي في خيوط مختلفة من برنامج، فقد تحدث سباقات بيانات. تستدعي glob() تلك الدوال، لذا نستخدم race:utent لتذكير المستخدمين.

POSIX.1-2008.

POSIX.1-2001, POSIX.2.

عناصر الهيكل gl_pathc و gl_offs مُصرَّح بها كـ size_t في glibc 2.1، كما ينبغي وفقًا لـ POSIX.2، لكنها مُصرَّح بها كـ int في glibc 2.0.

قد تفشل الدالة glob() بسبب فشل استدعاءات دوال أساسية، مثل malloc(3) أو opendir(3). ستُخزِّن هذه الدوال رمز خطئها في errno.

مثال واحد للاستخدام هو الكود التالي، الذي يحاكي كتابة

ls -l *.c ../*.c

في الصدفة:

glob_t globbuf;
globbuf.gl_offs = 2;
glob("*.c", GLOB_DOOFFS, NULL, &globbuf);
glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf);
globbuf.gl_pathv[0] = "ls";
globbuf.gl_pathv[1] = "-l";
execvp("ls", &globbuf.gl_pathv[0]);

ls(1), sh(1), stat(2), exec(3), fnmatch(3), malloc(3), opendir(3), readdir(3), wordexp(3), glob(7)

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

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

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