strerror(3)

الاسم
strerror, strerrorname_np, strerrordesc_np, strerror_r, strerror_l - إرجاع سلسلة محارف تصف رقم الخطأ

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

موجز
#include <string.h>

char *strerror(int errnum);
const char *strerrorname_np(int errnum);
const char *strerrordesc_np(int errnum);

int strerror_r(size_t size;
               int errnum, char buf[size], size_t size);
               /* XSI-compliant */

char *strerror_r(size_t size;
               int errnum, char buf[size], size_t size);
               /* GNU-specific */

char *strerror_l(int errnum, locale_t locale);

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

strerrorname_np(), strerrordesc_np():
    _GNU_SOURCE

strerror_r():
تُوفر النسخة المتوافقة مع معيار XSI إذا:
(_POSIX_C_SOURCE >= 200112L) && !_GNU_SOURCE
وإلا، تُوفر النسخة الخاصة بنظام GNU.

الوصف
الدالة strerror() تُعيد مؤشرًا إلى سلسلة محارف تصف رمز الخطأ المُمرَّر في المعامل errnum، وربما تستخدم جزء LC_MESSAGES من الإعدادات المحلية الحالية لاختيار اللغة المناسبة. (مثال: إذا كان errnum هو EINVAL، سيكون الوصف المُعاد "Invalid argument".) لا يجب تعديل هذه السلسلة بواسطة التطبيق، وسيُبطَل المؤشر المُعاد عند استدعاء لاحق لـ strerror() أو strerror_l()، أو إذا خرج الخيط الذي حصل على السلسلة. لا دالة مكتبة أخرى، بما في ذلك perror(3)، ستعدل هذه السلسلة.

مثل strerror()، الدالة strerrordesc_np() تُعيد مؤشرًا إلى سلسلة محارف تصف رمز الخطأ المُمرَّر في المعامل errnum، مع الفرق أن السلسلة المُعادة لا تُترجم وفقًا للإعدادات المحلية الحالية.

الدالة strerrorname_np() تُعيد مؤشرًا إلى سلسلة محارف تحتوي على اسم رمز الخطأ المُمرَّر في المعامل errnum. مثال: عند إعطاء EPERM كمعامل، تُعيد هذه الدالة مؤشرًا إلى السلسلة "EPERM". عند إعطاء 0 كمعامل، تُعيد هذه الدالة مؤشرًا إلى السلسلة "0".

  strerror_r()
strerror_r() تشبه strerror()، لكنها قد تستخدم المخزن المُوفَّر buf بدلاً من تخصيص واحد داخليًا. هذه الدالة متوفرة في إصدارين: إصدار متوافق مع XSI مُحدَّد في POSIX.1-2001 (متوفر منذ glibc 2.3.4، لكنه غير متوافق مع POSIX حتى glibc 2.13)، وإصدار خاص بـ GNU (متوفر منذ glibc 2.0). الإصدار المتوافق مع XSI يُوفَّر مع إعدادات وحدات الماكرو لاختبار الميزات الموضحة في الملخص؛ وإلا يُوفَّر الإصدار الخاص بـ GNU. إذا لم تُعرَّف وحدات ماكرو لاختبار الميزات صراحةً، فإنه (منذ glibc 2.4) _POSIX_C_SOURCE يُعرَّف مبدئيًا بالقيمة 200112L، بحيث يُوفَّر الإصدار المتوافق مع XSI من strerror_r() مبدئيًا.

إصدار strerror_r() المتوافق مع XSI هو المُفضَّل للتطبيقات القابلة للنقل. يُعيد سلسلة الخطأ في المخزن المُوفَّر من المستخدم buf بحجم size.

إصدار strerror_r() الخاص بـ GNU يُعيد مؤشرًا إلى سلسلة محارف تحتوي على رسالة الخطأ. قد يكون هذا إما مؤشرًا إلى سلسلة تخزنها الدالة في buf، أو مؤشرًا إلى سلسلة ثابتة (غير قابلة للتغيير) (وفي هذه الحالة لا يُستخدم buf). إذا خزنت الدالة سلسلة في buf، فسيُخزَّن على الأكثر size بايت (قد تُقتص السلسلة إذا كان size صغيرًا جدًا و errnum غير معروف). تحتوي السلسلة دائمًا على بايت ختامي صفري ('\0').

  strerror_l()
strerror_l() تشبه strerror()، لكنها تُعيّن errnum إلى رسالة خطأ معتمدة على الإعدادات المحلية في الإعدادات المحلية المُحدَّدة بواسطة locale. سلوك strerror_l() غير مُحدَّد إذا كان locale هو كائن الإعدادات المحلية الخاص LC_GLOBAL_LOCALE أو ليس مقبض كائن إعدادات محلية صالحًا.

قيمة الإرجاع
الدوال strerror() و strerror_l() و strerror_r() الخاص بـ GNU تُعيد سلسلة وصف الخطأ المناسبة، أو رسالة "Unknown error nnn" إذا كان رقم الخطأ غير معروف.

عند النجاح، تُعيد strerrorname_np() و strerrordesc_np() سلسلة وصف الخطأ المناسبة. إذا كان errnum رقم خطأ غير صالح، تُعيد هذه الدوال NULL.

الدالة strerror_r() المتوافقة مع XSI تُعيد 0 عند النجاح. عند الخطأ، يُعاد رقم خطأ (موجب) (منذ glibc 2.13)، أو يُعاد -1 ويُعيَّن errno للإشارة إلى الخطأ (قبل glibc 2.13).

تتطلب POSIX.1-2001 و POSIX.1-2008 أن استدعاءً ناجحًا لـ strerror() أو strerror_l() يجب أن يترك errno دون تغيير، وتلاحظ أنه نظرًا لعدم حجز قيمة إرجاع دالة للإشارة إلى خطأ، يجب على التطبيق الذي يرغب في التحقق من الأخطاء تهيئة errno إلى الصفر قبل الاستدعاء، ثم التحقق من errno بعد الاستدعاء.

الأخطاء

EINVAL
    قيمة errnum ليست رقم خطأ صالحًا.

ERANGE
    وُفرت مساحة تخزين غير كافية لاحتواء سلسلة محارف وصف الخطأ.

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

قبل glibc 2.32، strerror() ليس آمنًا للخيوط.

المعايير

strerror()
    C11, POSIX.1-2008.

strerror_r()
strerror_l()
    POSIX.1-2008.

strerrorname_np()
strerrordesc_np()
    GNU.

تسمح POSIX.1-2001 لـ strerror() بتعيين errno إذا واجه الاستدعاء خطأً، لكنها لا تحدد القيمة التي يجب إرجاعها كنتيجة للدالة في حالة حدوث خطأ. في بعض الأنظمة، تُرجع strerror() NULL إذا كان رقم الخطأ غير معروف. في أنظمة أخرى، تُرجع strerror() سلسلة محارف مثل "حدث خطأ nnn" وتُعيّن errno إلى EINVAL إذا كان رقم الخطأ غير معروف. تتطلب C99 و POSIX.1-2008 أن تكون القيمة المُرجعة غير NULL.

التاريخ

strerror()
    POSIX.1-2001، C89.

strerror_r()
    POSIX.1-2001.

strerror_l()
    glibc 2.6. POSIX.1-2008.

strerrorname_np()
strerrordesc_np()
    glibc 2.32.

ملاحظات
strerrorname_np() و strerrordesc_np() آمنان للخيوط وآمنان للإشارات غير المتزامنة.

انظر أيضًا
err(3)، errno(3)، error(3)، perror(3)، strsignal(3)، locale(7)، signal-safety(7)

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

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

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