getsubopt(3)

الاسم
getsubopt - تحليل وسائط الخيارات الفرعية من سلسلة محارف

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

موجز
#include <stdlib.h>

int getsubopt(char **restrict optionp, char *const *restrict tokens,
              char **restrict valuep);

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

getsubopt():
    _XOPEN_SOURCE >= 500
        || /* منذ glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

الوصف
getsubopt() يُحلل قائمة الخيارات الفرعية المفصولة بفواصل والمُقدمة في optionp. (تُنتج قائمة الخيارات الفرعية هذه عادةً عند استخدام getopt(3) لتحليل سطر أوامر؛ انظر مثلاً الخيار -o من mount(8).) قد يتضمن كل خيار فرعي قيمة مرتبطة، تُفصل عن اسم الخيار الفرعي بعلامة يساوي. فيما يلي مثال على نوع السلسلة التي قد تُمرر في optionp:

    ro,name=xyz

وسيط tokens هو مؤشر لمصفوفة منتهية بـ NULL من المؤشرات إلى الرموز التي سيبحث عنها getsubopt() في optionp. يجب أن تكون الرموز سلاسل محارف مميزة ومنتهية بـ null وتحتوي على حرف واحد على الأقل، دون علامات يساوي أو فواصل مضمنة.

كل استدعاء لـ getsubopt() يُرجع معلومات عن الخيار الفرعي التالي غير المعالج في optionp. تُفسر أول علامة يساوي في خيار فرعي (إن وُجدت) كفاصل بين اسم وقيمة ذلك الخيار الفرعي. تمتد القيمة إلى الفاصلة التالية، أو (للخيار الفرعي الأخير) إلى نهاية السلسلة. إذا طابق اسم الخيار الفرعي اسمًا معروفًا من tokens، ووُجدت سلسلة قيمة، يضبط getsubopt() *valuep على عنوان تلك السلسلة. تُستبدل أول فاصلة في optionp ببايت فارغ، لذا يكون *valuep بدقة "سلسلة القيمة" لذلك الخيار الفرعي.

إذا تم التعرف على الخيار الفرعي، ولكن لم تُوجد سلسلة قيمة، يُضبط *valuep على NULL.

عندما يُرجع getsubopt()، يشير optionp إلى الخيار الفرعي التالي، أو إلى البايت الفارغ ('\0') في نهاية السلسلة إذا كان الخيار الفرعي الأخير قد عُولج لتوه.

قيمة الإرجاع
إذا تم التعرف على أول خيار فرعي في optionp، يُرجع getsubopt() فهرس عنصر الخيار الفرعي المطابق في tokens. وإلا، يُرجع -1 ويكون *valuep هو السلسلة الكاملة name[=value].

بما أن *optionp قد تغير، فإن أول خيار فرعي قبل استدعاء getsubopt() ليس (بالضرورة) نفس أول خيار فرعي بعد getsubopt().

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

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

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

ملاحظات
بما أن getsubopt() يستبدل أي فواصل يجدها في السلسلة *optionp، يجب أن تكون تلك السلسلة قابلة للكتابة؛ لا يمكن أن تكون ثابت سلسلة.

أمثلة
يتوقع البرنامج التالي خيارات فرعية تتبع خيار "-o".

    #define _XOPEN_SOURCE 500
    #include <stdio.h>
    #include <stdlib.h>

    #include <assert.h>

    int
    main(int argc, char *argv[])
    {
        enum {
            RO_OPT = 0,
            RW_OPT,
            NAME_OPT
        };
        char *const token[] = {
            [RO_OPT]   = "ro",
            [RW_OPT]   = "rw",
            [NAME_OPT] = "name",
            NULL
        };
        char *subopts;
        char *value;
        int opt;

        int readonly = 0;
        int readwrite = 0;
        char *name = NULL;
        int errfnd = 0;

        while ((opt = getopt(argc, argv, "o:")) != -1) {
            switch (opt) {
            case 'o':
                subopts = optarg;
                while (*subopts != '\0' && !errfnd) {

                    switch (getsubopt(&subopts, token, &value)) {
                    case RO_OPT:
                        readonly = 1;
                        break;

                    case RW_OPT:
                        readwrite = 1;
                        break;

                    case NAME_OPT:
                        if (value == NULL) {
                            fprintf(stderr,
                                    "Missing value for suboption '%s'\n",
                                    token[NAME_OPT]);
                            errfnd = 1;
                            continue;
                        }

                        name = value;
                        break;

                    default:
                        fprintf(stderr,
                                "No match found for token: /%s/\n", value);
                        errfnd = 1;
                        break;
                    }
                }
                if (readwrite && readonly) {
                    fprintf(stderr,
                            "Only one of '%s' and '%s' can be specified\n",
                            token[RO_OPT], token[RW_OPT]);
                    errfnd = 1;
                }
                break;

            default:
                errfnd = 1;
            }
        }

        if (errfnd || argc == 1) {
            fprintf(stderr, "\nUsage: %s -o <suboptstring>\n", argv[0]);
            fprintf(stderr,
                    "suboptions are 'ro', 'rw', and 'name=<value>'\n");
            exit(EXIT_FAILURE);
        }

        /* Remainder of program...  */

        exit(EXIT_SUCCESS);
    }

انظر أيضًا
getopt(3)

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

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

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