wordexp(3)

الاسم
wordexp, wordfree - أداء توسيع الكلمات مثل قشرة posix

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

موجز
#include <wordexp.h>

int wordexp(const char *restrict s, wordexp_t *restrict p, int flags);
void wordfree(wordexp_t *p);

    متطلبات ماكروات اختبار الميزات لـ glibc (انظر feature_test_macros(7)):

wordexp()، wordfree():
    _XOPEN_SOURCE

الوصف
الدالة wordexp() تؤدي توسيعًا شبيهًا بالقشرة لسلسلة المحارف s وتُعيد النتيجة في البنية المشار إليها بواسطة p. نوع البيانات wordexp_t هو بنية تحتوي على الأقل على الحقول we_wordc وwe_wordv وwe_offs. الحقل we_wordc هو من نوع size_t يُعطي عدد الكلمات في توسيع s. الحقل we_wordv هو char ** يُشير إلى مصفوفة الكلمات التي وُجدت. الحقل we_offs من نوع size_t يُستخدم أحيانًا (اعتمادًا على flags، انظر أدناه) للإشارة إلى عدد العناصر الأولية في مصفوفة we_wordv التي ينبغي ملؤها بقيم NULL.

الدالة wordfree() تُحرر الذاكرة المُخصصة مرة أخرى. بشكل أدق، لا تُحرر وسيطها، بل تُحرر المصفوفة we_wordv وسلاسل المحارف التي تُشير إليها.

  وسيطة سلسلة المحارف
بما أن التوسيع هو نفس التوسيع بواسطة القشرة (انظر sh(1)) لمعاملات الأمر، فلا يجب أن تحتوي سلسلة المحارف s على محارف غير قانونية في معاملات أوامر القشرة. على وجه الخصوص، يجب ألا يكون هناك أي سطر جديد غير مُفلت أو محارف |، &، ;، <، >، (، )، {، } خارج سياق استبدال أمر أو استبدال معامل.

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

  التوسيع
يتكون التوسيع المُنجز من المراحل التالية: توسيع التلدة (استبدال ~user بدليل المستخدم الرئيس)، استبدال المتغير (استبدال $FOO بقيمة متغير البيئة FOO)، استبدال الأمر (استبدال $(command) أو `command` بمخرجات الأمر)، التوسيع الحسابي، تقسيم الحقول، توسيع أحرف البدل، إزالة الاقتباس.

نتيجة توسيع المعاملات الخاصة ($@، $*، $#، $?، $-، $$، $!، $0) غير مُحددة.

تقسيم الحقول يُنجز باستخدام متغير البيئة $IFS. إذا لم يُضبط، ففواصل الحقول هي المسافة، والتبويب، والسطر الجديد.

  مصفوفة المخرجات
المصفوفة we_wordv تحتوي على الكلمات التي وُجدت، متبوعة بقيمة NULL.

  معامل العلامات (flags)
وسيطة flag هي OR شامل على مستوى البت للقيم التالية:

WRDE_APPEND
    ألحق الكلمات التي وُجدت إلى المصفوفة الناتجة من استدعاء سابق.

WRDE_DOOFFS
    أدرج we_offs من القيم NULL الأولية في المصفوفة we_wordv. (لا تُحسب هذه في we_wordc المُرجَعة.)

WRDE_NOCMD
    لا تُجرِ استبدال الأوامر.

WRDE_REUSE
    المُعامل p نتج عن استدعاء سابق لـ wordexp()، ولم يُستدعَ wordfree(). أعد استخدام التخزين المُخصَّص.

WRDE_SHOWERR
    عادةً أثناء استبدال الأوامر، يُعاد توجيه stderr إلى /dev/null. تُحدد هذه العَلَمة أن stderr لا يُعاد توجيهه.

WRDE_UNDEF
    اعتبره خطأً إذا وُسِّع متغير شل غير مُعرَّف.

قيمة الإرجاع
عند النجاح، تُرجع wordexp() 0. عند الفشل، تُرجع wordexp() إحدى القيم غير الصفرية التالية:

WRDE_BADCHAR
    ظهور غير قانوني لسطر جديد أو أحد الرموز |, &, ;, <, >, (, ), {, }.

WRDE_BADVAL
    تمت الإشارة إلى متغير شل غير مُعرَّف، وأخبرتنا العَلَمة WRDE_UNDEF باعتبار هذا خطأً.

WRDE_CMDSUB
    طُلب استبدال الأوامر، لكن العَلَمة WRDE_NOCMD أخبرتنا باعتبار هذا خطأً.

WRDE_NOSPACE
    نفدت الذاكرة.

WRDE_SYNTAX
    خطأ في نحو الشل، مثل أقواس غير متوازنة أو علامات اقتباس غير متطابقة.

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
wordexp() | سلامة الخيوط | MT-Unsafe race:utent const:env env sig:ALRM timer locale
wordfree() | سلامة الخيوط | MT-Safe

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

المعايير
POSIX.1-2008.

التاريخ
POSIX.1-2001. glibc 2.1.

أمثلة
مخرج البرنامج المثالي التالي يقارب مخرج "ls [a-c]*.c".

    #include <stdio.h>
    #include <stdlib.h>
    #include <wordexp.h>

    int
    main(void)
    {
        wordexp_t p;
        char **w;

        wordexp("[a-c]*.c", &p, 0);
        w = p.we_wordv;
        for (size_t i = 0; i < p.we_wordc; i++)
            printf("%s\n", w[i]);
        wordfree(&p);
        exit(EXIT_SUCCESS);
    }

انظر أيضًا
fnmatch(3), glob(3)

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

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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