fmtmsg(3)

الاسم
fmtmsg - طباعة رسائل خطأ منسقة

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

موجز
#include <fmtmsg.h>

int fmtmsg(long classification, const char *label,
           int severity, const char *text,
           const char *action, const char *tag);

الوصف
تعرض هذه الدالة رسالة موصوفة بوسائطها على الجهاز (الأجهزة) المحدد في وسيط classification. بالنسبة للرسائل المكتوبة إلى stderr، يعتمد التنسيق على متغير البيئة MSGVERB.

يحدد وسيط label مصدر الرسالة. يجب أن تتكون سلسلة المحارف من جزأين مفصولين بنقطتين حيث لا يزيد الجزء الأول عن 10 أحرف والجزء الثاني عن 14 حرفًا.

يصف وسيط text حالة الخطأ.

يصف وسيط action الخطوات الممكنة للتعافي من الخطأ. إذا طُبع، يُسبق بـ "TO FIX: ".

وسيط tag هو مرجع للتوثيق عبر الإنترنت حيث يمكن العثور على مزيد من المعلومات. يجب أن يحتوي على قيمة label ورقم تعريف فريد.

  وسائط وهمية
يمكن أن يكون لكل وسيط قيمة وهمية. قيمة التصنيف الوهمية MM_NULLMC (0L) لا تحدد أي مخرجات، لذا لا يُطبع شيء. قيمة الشدة الوهمية NO_SEV (0) تشير إلى عدم توفير شدة. القيم MM_NULLLBL و MM_NULLTXT و MM_NULLACT و MM_NULLTAG هي مرادفات لـ ((char *) 0)، السلسلة الفارغة، و MM_NULLSEV هي مرادف لـ NO_SEV.

  وسيط التصنيف
وسيط classification هو مجموع القيم التي تصف 4 أنواع من المعلومات.

تحدد القيمة الأولى قناة الإخراج.

MM_PRINT
    الإخراج إلى stderr.

MM_CONSOLE
    الإخراج إلى وحدة التحكم في النظام.

MM_PRINT | MM_CONSOLE
    الإخراج إلى كليهما.

القيمة الثانية هي مصدر الخطأ:

MM_HARD
    حدث خطأ في العتاد.

MM_FIRM
    حدث خطأ في البرامج الثابتة.

MM_SOFT
    حدث خطأ في البرمجيات.

يُرمّز القيمة الثالثة كاشف المشكلة:

MM_APPL
    يُكتشف بواسطة تطبيق.

MM_UTIL
    يُكتشف بواسطة أداة مساعدة.

MM_OPSYS
    يُكتشف بواسطة نظام التشغيل.

يُظهر القيمة الرابعة شدة الحادثة:

MM_RECOVER
    إنه خطأ قابل للاسترداد.

MM_NRECOV
    إنه خطأ غير قابل للاسترداد.

  وسيطة الشدة
يمكن لوسيطة severity أن تأخذ إحدى القيم التالية:

MM_NOSEV
    لا تُطبع أي شدة.

MM_HALT
    تُطبع هذه القيمة كـ HALT.

MM_ERROR
    تُطبع هذه القيمة كـ ERROR.

MM_WARNING
    تُطبع هذه القيمة كـ WARNING.

MM_INFO
    تُطبع هذه القيمة كـ INFO.

القيم الرقمية بين 0 و4. باستخدام addseverity(3) أو متغير البيئة SEV_LEVEL يمكنك إضافة مستويات وسلاسل محارف إضافية للطباعة.

قيمة الإرجاع
يمكن للدالة أن تُرجع 4 قيم:

MM_OK
    سار كل شيء بسلاسة.

MM_NOTOK
    فشل كامل.

MM_NOMSG
    خطأ في الكتابة إلى stderr.

MM_NOCON
    خطأ في الكتابة إلى وحدة التحكم.

البيئة
يمكن استخدام متغير البيئة MSGVERB ("إسهاب الرسالة") لكبت أجزاء من المخرجات إلى stderr. (لا يؤثر على المخرجات إلى وحدة التحكم.) عندما يُعرّف هذا المتغير، ويكون غير NULL، ويكون قائمة مفصولة بنقطتين من الكلمات المفتاحية الصالحة، فعندها تُطبع فقط أجزاء الرسالة المطابقة لهذه الكلمات المفتاحية. الكلمات المفتاحية الصالحة هي "label" و"severity" و"text" و"action" و"tag".

يمكن استخدام متغير البيئة SEV_LEVEL لإدخال مستويات شدة جديدة. مبدئيًا، تتوفر فقط مستويات الشدة الخمسة الموصوفة أعلاه. أي قيمة عددية أخرى ستجعل fmtmsg() لا يطبع شيئًا. إذا وضع المستخدم SEV_LEVEL بتنسيق مثل

    SEV_LEVEL=[وصف[:وصف[:...]]]

في بيئة العملية قبل أول استدعاء لـ fmtmsg()، حيث يكون كل وصف بالشكل

    كلمة-شدة،مستوى،سلسلة-طباعة

عندها سيقبل fmtmsg() أيضًا القيم المشار إليها للمستوى (بالإضافة إلى المستويات القياسية 0–4)، وسيستخدم سلسلة الطباعة المشار إليها عند حدوث مثل هذا المستوى.

الجزء الخاص بكلمة الشدة لا يُستخدم بواسطة fmtmsg() لكن يجب أن يكون موجودًا. جزء المستوى هو تمثيل سلسلة محارف لرقم. يجب أن تكون القيمة العددية رقمًا أكبر من 4. يجب استخدام هذه القيمة في وسيط الشدة لـ fmtmsg() لاختيار هذه الفئة. لا يمكن الكتابة فوق أي من الفئات المحددة مسبقًا. سلسلة الطباعة هي السلسلة المطبوعة عند معالجة رسالة من هذه الفئة بواسطة fmtmsg().

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
fmtmsg() | سلامة الخيوط | glibc >= 2.16: MT-Safe; glibc < 2.16: MT-Unsafe

قبل glibc 2.16، تستخدم دالة fmtmsg() متغيرًا ثابتًا غير محمي، لذا فهي غير آمنة متعددة الخيوط.

منذ glibc 2.16، تستخدم دالة fmtmsg() قفلًا لحماية المتغير الثابت، لذا فهي آمنة متعددة الخيوط.

المعايير

fmtmsg()
MSGVERB
    POSIX.1-2008.

التاريخ

fmtmsg()
    System V. POSIX.1-2001 و POSIX.1-2008. glibc 2.1.

MSGVERB
    System V. POSIX.1-2001 و POSIX.1-2008.

SEV_LEVEL
    System V.

تخبرنا صفحات دليل System V و UnixWare أن هذه الدوال قد استُبدلت بـ "pfmt() و addsev()" أو بـ "pfmt()، vpfmt()، lfmt()، و vlfmt()"، وسيتم إزالتها لاحقًا.

أمثلة
    #include <fmtmsg.h>
    #include <stdio.h>
    #include <stdlib.h>

    int
    main(void)
    {
        long c = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
        int err;

        err = fmtmsg(c, "util-linux:mount", MM_ERROR,
                     "unknown mount option", "See mount(8).",
                     "util-linux:mount:017");
        switch (err) {
        case MM_OK:
            break;
        case MM_NOTOK:
            printf("Nothing printed\n");
            break;
        case MM_NOMSG:
            printf("Nothing printed to stderr\n");
            break;
        case MM_NOCON:
            printf("No console output\n");
            break;
        default:
            printf("Unknown error from fmtmsg()\n");
        }
        exit(EXIT_SUCCESS);
    }

يجب أن يكون المخرج:

    util-linux:mount: ERROR: unknown mount option
    TO FIX: See mount(8).  util-linux:mount:017

وبعد

    MSGVERB=text:action; export MSGVERB

يصبح المخرج:

    unknown mount option
    TO FIX: See mount(8).

انظر أيضًا
addseverity(3), perror(3)

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

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

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