readdir_r(3)

الاسم
readdir_r - يقرأ دليلاً

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

موجز
#include <dirent.h>

[[deprecated]] int readdir_r(DIR *restrict dirp,
                             struct dirent *restrict entry,
                             struct dirent **restrict result);

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

readdir_r():
    _POSIX_C_SOURCE
        || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE

الوصف
هذه الدالة مهملة؛ استخدم readdir(3) بدلاً منها.

الدالة readdir_r() صُممت كنسخة قابلة لإعادة الدخول من readdir(3). تقرأ إدخال الدليل التالي من دفق الدليل dirp، وتُرجعه في المخزن المؤقت المُخصص من قبل المستدعي والمشار إليه بواسطة entry. لتفاصيل بنية dirent، انظر readdir(3).

يُوضع مؤشر إلى المخزن المؤقت المُعاد في *result؛ إذا تم الوصول إلى نهاية دفق الدليل، فإن NULL يُعاد بدلاً من ذلك في *result.

يُوصى بأن تستخدم التطبيقات readdir(3) بدلاً من readdir_r(). علاوة على ذلك، منذ glibc 2.24، تُهمل glibc readdir_r(). الأسباب كالتالي:

•   على الأنظمة حيث NAME_MAX غير مُعرّف، قد يكون استدعاء readdir_r() غير آمن لأن الواجهة لا تسمح للمستدعي بتحديد طول المخزن المؤقت المستخدم لإدخال الدليل المُعاد.

•   على بعض الأنظمة، لا تستطيع readdir_r() قراءة إدخالات دليل بأسماء طويلة جداً. عندما يواجه تطبيق glibc مثل هذا الاسم، تفشل readdir_r() مع الخطأ ENAMETOOLONG بعد قراءة إدخال الدليل الأخير. على بعض الأنظمة الأخرى، قد تُرجع readdir_r() حالة نجاح، لكن الحقل d_name المُعاد قد لا يكون منتهياً بصفر أو قد يكون مبتوراً.

•   في مواصفات POSIX.1 الحالية (POSIX.1-2008)، readdir(3) ليست مطلوبة لتكون آمنة للخيوط. ومع ذلك، في التطبيقات الحديثة (بما في ذلك تطبيق glibc)، الاستدعاءات المتزامنة لـ readdir(3) التي تُحدد تدفقات دليل مختلفة هي آمنة للخيوط. لذلك، استخدام readdir_r() غير ضروري عموماً في البرامج متعددة الخيوط. في الحالات حيث يجب أن تقرأ خيوط متعددة من نفس دفق الدليل، استخدام readdir(3) مع مزامنة خارجية لا يزال أفضل من استخدام readdir_r()، للأسباب المذكورة في النقاط أعلاه.

•   من المتوقع أن تجعل نسخة مستقبلية من POSIX.1 readdir_r() مهملة، وتتطلب أن تكون readdir(3) آمنة للخيوط عند استخدامها بشكل متزامن على تدفقات دليل مختلفة.

قيمة الإرجاع
الدالة readdir_r() تُرجع 0 عند النجاح. عند الخطأ، تُرجع رقم خطأ موجب (مُدرج تحت الأخطاء). إذا تم الوصول إلى نهاية دفق الدليل، تُرجع readdir_r() 0، وتُعيد NULL في *result.

الأخطاء

EBADF
    واصف تدفق دليل dirp غير صالح.

ENAMETOOLONG
    تمت مواجهة إدخال دليل كان اسمه طويلاً جداً بحيث لا يمكن قراءته.

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

المعايير
POSIX.1-2008.

التاريخ
POSIX.1-2001.

انظر أيضًا
readdir(3)

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

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

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