ERR_PUT_ERROR(3SSL)

الاسم
ERR_raise, ERR_raise_data, ERR_put_error, ERR_add_error_data, ERR_add_error_vdata, ERR_add_error_txt, ERR_add_error_mem_bio - تسجيل خطأ

موجز
 #include <openssl/err.h>

 void ERR_raise(int lib, int reason);
 void ERR_raise_data(int lib, int reason, const char *fmt, ...);

 void ERR_add_error_data(int num, ...);
 void ERR_add_error_vdata(int num, va_list arg);
 void ERR_add_error_txt(const char *sep, const char *txt);
 void ERR_add_error_mem_bio(const char *sep, BIO *bio);

الدالة التالية أصبحت مهجورة منذ OpenSSL 3.0، ويمكن إخفاؤها تمامًا عبر تعريف OPENSSL_API_COMPAT بقيمة إصدار مناسبة، انظر openssl_user_macros(7):

 void ERR_put_error(int lib, int func, int reason, const char *file, int line);

الوصف
ERR_raise() تُضيف خطأً جديدًا إلى طابور أخطاء الخيط. حدث الخطأ في المكتبة lib للسبب المُعطى بواسطة كود reason. علاوةً على ذلك، يُحفظ اسم الملف، السطر، واسم الدالة حيث حدث الخطأ مع سجل الخطأ.

ERR_raise_data() يفعل نفس الشيء مثل ERR_raise()، لكنه يسمح أيضًا للمُستدعي بتحديد معلومات إضافية كسلسلة تنسيق fmt وعدد عشوائي من القيم، والتي تُعالج باستخدام BIO_snprintf(3).

ERR_put_error() تُضيف كود خطأ إلى طابور أخطاء الخيط. تُشير إلى أن خطأ كود السبب reason حدث في الدالة func من المكتبة lib، في رقم السطر line من file. تُستدعى هذه الدالة عادةً بواسطة ماكرو.

ERR_add_error_data() يُربط تسلسل وسائط سلسلة المحارف num الخاصة به كبيانات إضافية مع كود الخطأ المُضاف آخرًا. ERR_add_error_vdata() مشابه باستثناء أن الوسيطة هي va_list. تُلحق الاستدعاءات المتعددة لهذه الدوال بالجزء العلوي الحالي لقائمة انتظار الأخطاء. يُحدد الطول الإجمالي لبيانات سلسلة المحارف لكل خطأ بـ 4096 حرفًا.

ERR_add_error_txt() يُلحق سلسلة المحارف النصية المُعطاة كبيانات إضافية بآخر إدخال في قائمة انتظار الأخطاء، بعد إدراج سلسلة الفاصل الاختيارية إذا لم تكن NULL ولم يحتوي إدخال الخطأ العلوي بعد على بيانات إضافية. في حالة وجود الفاصل في نهاية النص، لا يُلحق بالبيانات. قد تكون وسيطة sep مثلاً "\n" لإدراج فاصل سطر عند الحاجة. إذا أصبحت البيانات المرتبطة أطول من 4096 حرفًا (وهو الحد المُعطى أعلاه)، تُقسم عبر عدد كافٍ من النسخ الجديدة لآخر إدخال في قائمة انتظار الأخطاء.

ERR_add_error_mem_bio() مماثلة لـ ERR_add_error_txt() باستثناء أن سلسلة المحارف النصية تُؤخذ من BIO الذاكرة المُعطى. تُلحق '\0' بمحتويات BIO إذا لم تكن مُنتهية بـ NUL بالفعل.

ERR_load_strings(3) يمكن استخدامه لتسجيل سلاسل محارف الأخطاء بحيث يمكن للتطبيق إنشاء رسائل خطأ قابلة للقراءة البشرية لكود الخطأ.

  الإبلاغ عن الأخطاء
تقارير مكتبة OpenSSL

كل مكتبة فرعية من OpenSSL لها كود مكتبة ERR_LIB_XXX ولها مجموعتها الخاصة من أكواد السبب XXX_R_.... يُمرر كلاهما معًا إلى ERR_raise() و ERR_raise_data()، ويُنتج التركيبة في النهاية نص الخطأ الصحيح للخطأ المُبلغ عنه.

كل هذه الماكروهات والأرقام التي تمتلكها كقيم خاصة بمكتبات OpenSSL. تتكون أكواد أسباب OpenSSL عادةً من أوصاف أخطاء نصية. على سبيل المثال، تُبلغ الدالة ssl3_read_bytes() عن "فشل المصافحة" كما يلي:

 ERR_raise(ERR_LIB_SSL, SSL_R_SSL_HANDSHAKE_FAILURE);

هناك استثناءان:

ERR_LIB_SYS
    يشير "رمز المكتبة" هذا إلى أنه يتم الإبلاغ عن خطأ نظام. في هذه الحالة، يجب أن يكون رمز السبب المُعطى لـ ERR_raise() و ERR_raise_data() هو errno(3).

     ERR_raise(ERR_LIB_SYS, errno);

ERR_R_XXX
    تُعتبر هذه المجموعة من رموز الأخطاء عامة، ويمكن استخدامها مع أي رمز مكتبة فرعية.

     ERR_raise(ERR_LIB_RSA, ERR_R_PASSED_INVALID_ARGUMENT);

أجزاء البرامج الأخرى

قطع البرامج الأخرى التي قد ترغب في استخدام نظام الإبلاغ عن الأخطاء الخاص بـ OpenSSL، مثل المحركات أو التطبيقات، يجب أن تحصل عادةً على أرقامها الخاصة.

•   للحصول على رمز "مكتبة"، استدعِ ERR_get_next_error_library(3)؛ يعطي هذا رمزًا ديناميكيًا للكود المستدعي، قابل للاستخدام طوال مدة العملية.

•   يتم تحديد أو توليد رموز السبب لكل "مكتبة" من هذا القبيل بواسطة مؤلفي ذلك الكود. يجب أن تكون أرقامًا في النطاق من 1 إلى 524287 (بمعنى آخر، يجب أن تكون أعدادًا صحيحة غير صفرية غير موقعة بطول 18 بت).

الاستثناءات المذكورة في "تقارير مكتبة OpenSSL" أعلاه صالحة لأجزاء البرامج الأخرى، أي يمكنها استخدام ERR_LIB_SYS للإبلاغ عن أخطاء النظام:

 ERR_raise(ERR_LIB_SYS, errno);

... ويمكنها استخدام وحدات ماكرو ERR_R_XXX مع رمز "المكتبة" الخاص بها.

 int app_lib_code = ERR_get_next_error_library();

 /* ... */

 ERR_raise(app_lib_code, ERR_R_PASSED_INVALID_ARGUMENT);

القيم المُرجعة
لا تُرجع ERR_raise()، ERR_raise_data()، ERR_put_error()، ERR_add_error_data()، ERR_add_error_vdata() ERR_add_error_txt()، و ERR_add_error_mem_bio() أي قيم.

ملاحظات
ERR_raise()، ERR_raise() و ERR_put_error() مُنفذة كوحدات ماكرو.

انظر أيضًا
ERR_load_strings(3)، ERR_get_next_error_library(3)

التاريخ
أُضيفت ERR_raise، ERR_raise_data، ERR_add_error_txt() و ERR_add_error_mem_bio() في OpenSSL 3.0.

حقوق النسخ
حقوق النشر 2000-2020 لمؤلفي مشروع OpenSSL. جميع الحقوق محفوظة.

مرخص بموجب رخصة Apache 2.0 (المشار إليها فيما يلي بـ ”الرخصة“). لا يجوز لك استخدام هذا الملف إلا وفقًا لشروط الرخصة. يمكنك الحصول على نسخة منها في الملف LICENSE الموجود في حزمة التوزيع المصدرية أو على الرابط <https://www.openssl.org/source/license.html>.

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

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

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