الاسم¶

getopt, 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;

getopt():

    _POSIX_C_SOURCE >= 2 || _XOPEN_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() بالمثل لا تطبع رسالة خطأ. بالإضافة إلى ذلك، تُعيد ':' بدلاً من '?' للإشارة إلى وسيط خيار مفقود. هذا يسمح للمستدعي بالتمييز بين نوعي الخطأ المختلفين.

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

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

البيئة¶

POSIXLY_CORRECT

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

السمات¶

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

الإصدارات¶

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

المعايير¶

getopt()

POSIX.1-2008.

استخدام '+' و '-' في 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>.

تأثرت الإصدارات القديمة جدًا من glibc بمتغير البيئة _PID_GNU_nonoption_argv_flags_.

ملاحظات¶

البرنامج الذي يمسح متجهات وسائط متعددة، أو يعيد مسح نفس المتجه أكثر من مرة، ويريد استخدام امتدادات 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);
}

انظر أيضًا¶

getopt(1)، getopt_long(3)، getopt_long_only(3)، getsubopt(3)

ترجمة¶

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

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

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