الاسم¶

getopt, getopt_long, getopt_long_only, optarg, optind, opterr, optopt - تحليل خيارات سطر الأوامر

المكتبة¶

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

موجز¶

#include <unistd.h>

int getopt(int argc, char *argv[],
           const char *optstring);

extern char *optarg;
extern int optind, opterr, optopt;

#include <getopt.h>

int getopt_long(int argc, char *argv[],
           const char *optstring,
           const struct option *longopts, int *longindex);
int getopt_long_only(int argc, char *argv[],
           const char *optstring,
           const struct option *longopts, int *longindex);

getopt():

    _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE

getopt_long()، getopt_long_only() :

    _GNU_SOURCE

الوصف¶

الدالة getopt() تحلل وسائط سطر الأوامر. وسيطاها argc و argv هما عدد الوسائط والمصفوفة كما تم تمريرهما إلى الدالة main() عند استدعاء البرنامج. عنصر من argv يبدأ بـ '-' (وليس بالضبط "-" أو "--") هو عنصر خيار. محارف هذا العنصر (باستثناء '-' الأولي) هي محارف خيار. إذا استُدعيت getopt() بشكل متكرر، فإنها تُرجع تباعًا كل محرف خيار من كل عنصر خيار.

المتغير optind هو فهرس العنصر التالي الذي سيُعالج في argv. يُهيئ النظام هذه القيمة إلى 1. يمكن للمستدعي إعادة تعيينها إلى 1 لإعادة مسح نفس argv، أو عند مسح متجه وسائط جديد.

إذا وجدت getopt() محرف خيار آخر، فإنها تُرجع ذلك المحرف، مُحدّثة المتغير الخارجي optind والمتغير الثابت nextchar بحيث يمكن للاستدعاء التالي لـ getopt() استئناف المسح بمحرف الخيار التالي أو عنصر argv.

إذا لم يكن هناك المزيد من محارف الخيار، تُرجع getopt() -1. عندها يكون optind هو الفهرس في argv لأول عنصر argv ليس خيارًا.

optstring هو سلسلة محارف تحتوي على محارف الخيار المشروعة. محرف الخيار المشروع هو أي محرف ascii(7) مرئي ذو بايت واحد (الذي ستعيد له isgraph(3) قيمة غير صفرية) وليس '-' أو ':' أو ';'. إذا تبع هذا المحرف نقطتان رأسيتان، فإن الخيار يتطلب وسيطًا، لذا تضع getopt() مؤشرًا إلى النص التالي في نفس عنصر argv، أو نص عنصر argv التالي، في optarg. نقطتان رأسيتان تعنيان أن الخيار يأخذ وسيطًا اختياريًا؛ إذا كان هناك نص في عنصر argv الحالي (أي في نفس الكلمة مثل اسم الخيار نفسه، على سبيل المثال، "-oarg")، فإنه يُعاد في optarg، وإلا يُضبط optarg إلى صفر. هذا امتداد لـ GNU. إذا احتوى optstring على W متبوعًا بفاصلة منقوطة، فإن -W foo يُعالج كخيار طويل --foo. (خيار -W محجوز بواسطة POSIX.2 لامتدادات التنفيذ.) هذا السلوك هو امتداد لـ GNU، غير متوفر مع المكتبات قبل glibc 2.

افتراضيًا، يُبدل getopt() محتويات argv أثناء مسحها، بحيث تكون جميع العناصر غير الخيارية في النهاية. يُنفذ أيضًا وضعان آخران للمسح. إذا كان الحرف الأول من optstring هو '+' أو تم تعيين متغير البيئة POSIXLY_CORRECT، فإن معالجة الخيار تتوقف فور مواجهة وسيطة غير خيارية. إذا لم يكن '+' هو الحرف الأول من optstring، فيُعامل كخيار عادي. إذا كان سلوك POSIXLY_CORRECT مطلوبًا في هذه الحالة، فسيحتوي optstring على رمزين '+'. إذا كان الحرف الأول من optstring هو '-'، فسيتم التعامل مع كل عنصر argv غير خياري كما لو كان وسيطة خيار برمز حرف 1. (يُستخدم هذا بواسطة البرامج التي كُتبت لتتوقع خيارات وعناصر argv أخرى بأي ترتيب وتهتم بترتيبهما.) الوسيطة الخاصة "--" تُجبر إنهاء مسح الخيار بغض النظر عن وضع المسح.

أثناء معالجة قائمة الخيارات، يمكن لـ getopt() اكتشاف نوعين من الأخطاء: (1) محرف خيار لم يُحدد في optstring و(2) وسيط خيار مفقود (أي خيار في نهاية سطر الأوامر بدون وسيط متوقع). تُعالج هذه الأخطاء وتُبلغ عنها كما يلي:

•

بشكل مبدئي، تطبع getopt() رسالة خطأ على الخطأ المعياري، وتضع محرف الخيار الخاطئ في optopt، وتُعيد '?' كنتيجة للدالة.

•

إذا ضبط المستدعي المتغير العام opterr إلى صفر، فإن getopt() لا تطبع رسالة خطأ. يمكن للمستدعي تحديد وجود خطأ باختبار ما إذا كانت قيمة إرجاع الدالة هي '?'. (بشكل مبدئي، opterr له قيمة غير صفرية.)

•

إذا كان المحرف الأول (بعد أي '+' أو '-' اختياري موصوف أعلاه) من optstring هو نقطتان رأسيتان (':')، فإن getopt() بالمثل لا تطبع رسالة خطأ. بالإضافة إلى ذلك، تُعيد ':' بدلاً من '?' للإشارة إلى وسيط خيار مفقود. هذا يسمح للمستدعي بالتمييز بين نوعي الخطأ المختلفين.

struct option {


    const char *name;


    int         has_arg;


    int        *flag;


    int         val;
};

قيمة الإرجاع¶

إذا وُجد خيار بنجاح، فإن getopt() تُعيد محرف الخيار. إذا حُللت جميع خيارات سطر الأوامر، فإن getopt() تُعيد -1. إذا واجهت getopt() محرف خيار لم يكن في optstring، فإن '?' يُعاد. إذا واجهت getopt() خيارًا بوسيط مفقود، فإن قيمة الإرجاع تعتمد على المحرف الأول في optstring: إذا كان ':'، فإن ':' يُعاد؛ وإلا يُعاد '?'.

getopt_long() وgetopt_long_only() تُرجعان أيضًا حرف الخيار عند التعرف على خيار قصير. بالنسبة لخيار طويل، تُرجعان val إذا كان flag هو NULL، و0 بخلاف ذلك. إرجاعات الخطأ و-1 هي نفسها لـ getopt()، بالإضافة إلى '?' للمطابقة الغامضة أو معامل زائد.

البيئة¶

POSIXLY_CORRECT

إذا كان هذا مضبوطًا، فإن معالجة الخيار تتوقف فور مواجهة وسيط غير خيار.

_<PID>_GNU_nonoption_argv_flags_

استُخدم هذا المتغير بواسطة bash(1) 2.0 للتواصل مع glibc حول الوسائط التي هي نتائج توسيع أحرف البدل وبالتالي لا ينبغي اعتبارها خيارات. أُزيل هذا السلوك في bash(1) 2.01، لكن الدعم لا يزال موجودًا في glibc.

السمات¶

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

الإصدارات¶

يحدد POSIX أن وسيط المصفوفة argv يجب أن يكون const، لكن هذه الدوال تبدل عناصرها ما لم يُضبط متغير البيئة POSIXLY_CORRECT. يُستخدم const في النموذج الأولي الفعلي للتوافق مع الأنظمة الأخرى؛ لكن هذه الصفحة لا تُظهر المؤهل، لتجنب إرباك القراء.

المعايير¶

getopt()

POSIX.1-2008.

getopt_long()

getopt_long_only()

GNU.

استخدام '+' و '-' في optstring هو امتداد لـ GNU.

التاريخ¶

getopt()

POSIX.1-2001، وPOSIX.2.

في بعض التطبيقات القديمة، أُعلنت getopt() في <stdio.h>. سمح SUSv1 بظهور الإعلان إما في <unistd.h> أو <stdio.h>. وسم POSIX.1-1996 استخدام <stdio.h> لهذا الغرض بأنه قديم (LEGACY). لا يتطلب POSIX.1-2001 ظهور الإعلان في <stdio.h>.

ملاحظات¶

برنامج يمسح متجهات وسائط متعددة، أو يعيد مسح نفس المتجه أكثر من مرة، ويريد استخدام إضافات GNU مثل '+' و '-' في بداية optstring، أو يغير قيمة POSIXLY_CORRECT بين عمليات المسح، يجب أن يعيد تهيئة getopt() بإعادة ضبط optind إلى 0، بدلاً من القيمة التقليدية 1. (إعادة الضبط إلى 0 تُجبر استدعاء روتين تهيئة داخلي يعيد فحص POSIXLY_CORRECT ويتحقق من إضافات GNU في optstring.)

تُحلل وسائط سطر الأوامر بترتيب صارم، مما يعني أن الخيار الذي يتطلب وسيطة سيستهلك الوسيطة التالية، بغض النظر عما إذا كانت تلك الوسيطة هي وسيطة الخيار المحددة بشكل صحيح أو مجرد الخيار التالي (في السيناريو الذي يحدد فيه المستخدم سطر الأوامر بشكل خاطئ). على سبيل المثال، إذا تم تحديد optstring كـ "1n:" وحدد المستخدم وسائط سطر الأوامر بشكل غير صحيح كـ prog -n -1، فسيتم إعطاء الخيار -n قيمة optarg "-1"، وسيُعتبر الخيار -1 غير محدد.

أمثلة¶

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
int
main(int argc, char *argv[])
{


    int flags, opt;


    int nsecs, tfnd;


    nsecs = 0;


    tfnd = 0;


    flags = 0;


    while ((opt = getopt(argc, argv, "nt:")) != -1) {


        switch (opt) {


        case 'n':


            flags = 1;


            break;


        case 't':


            nsecs = atoi(optarg);


            tfnd = 1;


            break;


        default: /* '?' */


            fprintf(stderr, "Usage: %s [-t nsecs] [-n] name\n",


                    argv[0]);


            exit(EXIT_FAILURE);


        }


    }


    printf("flags=%d; tfnd=%d; nsecs=%d; optind=%d\n",


           flags, tfnd, nsecs, optind);


    if (optind >= argc) {


        fprintf(stderr, "Expected argument after options\n");


        exit(EXIT_FAILURE);


    }


    printf("name argument = %s\n", argv[optind]);


    /* Other code omitted */


    exit(EXIT_SUCCESS);
}

#include <getopt.h>
#include <stdio.h>     /* for printf */
#include <stdlib.h>    /* for exit */
int
main(int argc, char *argv[])
{


    int c;


    int digit_optind = 0;


    while (1) {


        int this_option_optind = optind ? optind : 1;


        int option_index = 0;


        static struct option long_options[] = {


            {"add",     required_argument, 0,  0 },


            {"append",  no_argument,       0,  0 },


            {"delete",  required_argument, 0,  0 },


            {"verbose", no_argument,       0,  0 },


            {"create",  required_argument, 0, 'c'},


            {"file",    required_argument, 0,  0 },


            {0,         0,                 0,  0 }


        };


        c = getopt_long(argc, argv, "abc:d:012",


                        long_options, &option_index);


        if (c == -1)


            break;


        switch (c) {


        case 0:


            printf("option %s", long_options[option_index].name);


            if (optarg)


                printf(" with arg %s", optarg);


            printf("\n");


            break;


        case '0':


        case '1':


        case '2':


            if (digit_optind != 0 && digit_optind != this_option_optind)


              printf("digits occur in two different argv-elements.\n");


            digit_optind = this_option_optind;


            printf("option %c\n", c);


            break;


        case 'a':


            printf("option a\n");


            break;


        case 'b':


            printf("option b\n");


            break;


        case 'c':


            printf("option c with value '%s'\n", optarg);


            break;


        case 'd':


            printf("option d with value '%s'\n", optarg);


            break;


        case '?':


            break;


        default:


            printf("?? getopt returned character code 0%o ??\n", c);


        }


    }


    if (optind < argc) {


        printf("non-option ARGV-elements: ");


        while (optind < argc)


            printf("%s ", argv[optind++]);


        printf("\n");


    }


    exit(EXIT_SUCCESS);
}

انظر أيضًا¶

getopt(1)، getsubopt(3)

ترجمة¶

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

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

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