readdir(3)

الاسم
readdir - قراءة دليل

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

موجز
#include <dirent.h>

struct dirent *readdir(DIR *dirp);

الوصف
ترجع الدالة readdir() مؤشرًا إلى بنية dirent تمثل إدخال الدليل التالي في دفق الدليل المشار إليه بواسطة dirp. وترجع NULL عند الوصول إلى نهاية دفق الدليل أو في حالة حدوث خطأ.

في تطبيق glibc، تُعرف بنية dirent كما يلي:

    struct dirent {
        ino_t          d_ino;       /* رقم العقدة */
        off_t          d_off;       /* ليس إزاحة انظر في الأسفل */
        unsigned short d_reclen;    /* طول هذا السجل */
        unsigned char  d_type;      /* نوع الملف؛ غير متاح
                                       على على أنظمة الملفات*/
        char           d_name[256]; /* اسم ملف منتهي بnull */
    };

الحقول الوحيدة في بنية dirent التي يفرضها POSIX.1 هي .d_name و .d_ino. الحقول الأخرى غير معيارية، وغير موجودة في جميع الأنظمة؛ انظر VERSIONS.

حقول بنية dirent هي كما يلي:

.d_ino
    هذا هو رقم inode للملف في نظام الملفات الذي يحتوي على الدليل الذي استُدعيت عليه readdir(). إذا كان إدخال الدليل نقطة وصل، فإن .d_ino يختلف عن .st_ino الذي ترجعه stat(2) على هذا الملف: .d_ino هو رقم inode لنقطة الوصل، بينما .st_ino هو رقم inode للدليل الجذر لنظام الملفات الموصول.

.d_off
    القيمة المرجعة في .d_off هي نفسها التي سترجعها استدعاء telldir(3) في الموضع الحالي في دفق الدليل. كن على علم أنه على الرغم من نوعه واسمه، فإن حقل .d_off نادرًا ما يكون أي نوع من إزاحة الدليل في أنظمة الملفات الحديثة. يجب على التطبيقات معاملة هذا الحقل كقيمة غير شفافة، دون افتراضات حول محتوياته؛ انظر أيضًا telldir(3).

.d_reclen
    هذا هو حجم (بالبايت) السجل المرتجع. قد لا يتطابق هذا مع حجم تعريف البنية الموضح أعلاه؛ انظر VERSIONS.

.d_type
    يحتوي هذا الحقل على قيمة تشير إلى نوع الملف، مما يجعل من الممكن تجنب تكلفة استدعاء lstat(2) إذا كانت الإجراءات الإضافية تعتمد على نوع الملف.

    عند تعريف ماكرو اختبار ميزة مناسب (_DEFAULT_SOURCE منذ glibc 2.19، أو _BSD_SOURCE على glibc 2.19 والإصدارات الأقدم)، يعرف glibc الثوابت الماكرو التالية للقيمة المرجعة في .d_type:

    DT_BLK
        هذا جهاز كتلي.

    DT_CHR
        هذا جهاز محرفي.

    DT_DIR
        هذا دليل.

    DT_FIFO
        هذا أنبوب مسمى (FIFO).

    DT_LNK
        هذا رابط رمزي.

    DT_REG
        هذا ملف عادي.

    DT_SOCK
        هذا مقبس نطاق UNIX.

    DT_UNKNOWN
        لم يمكن تحديد نوع الملف.

    حاليًا، فقط بعض أنظمة الملفات (من بينها: Btrfs، ext2، ext3، و ext4) لديها دعم كامل لإرجاع نوع الملف في .d_type. يجب على جميع التطبيقات معالجة إرجاع DT_UNKNOWN بشكل صحيح.

.d_name
    يحتوي هذا الحقل على اسم الملف المنتهي بقيمة فارغة؛ انظر VERSIONS.

البيانات التي تُرجعها readdir() قد تُستبدل باستدعاءات لاحقة لـ readdir() لنفس دفق الدليل.

قيمة الإرجاع
عند النجاح، تُرجع readdir() مؤشرًا إلى بنية dirent. (قد تُخصص هذه البنية بشكل ثابت؛ لا تحاول تحريرها بـ free(3).)

إذا وُصلت نهاية دفق الدليل، يُرجع NULL ولا يُغير errno. إذا حدث خطأ، يُرجع NULL ويُضبط errno للإشارة إلى الخطأ. للتمييز بين نهاية الدفق والخطأ، اضبط errno على الصفر قبل استدعاء readdir() ثم تحقق من قيمة errno إذا أُرجع NULL.

الأخطاء

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

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

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

الإصدارات
فقط الحقول .d_name و (كإضافة XSI) .d_ino مُحددة في POSIX.1. بخلاف Linux، الحقل .d_type متاح بشكل رئيسي فقط على أنظمة BSD. الحقول المتبقية متاحة على العديد من الأنظمة، ولكن ليس كلها. تحت glibc، يمكن للبرامج التحقق من توفر الحقول غير المُعرفة في POSIX.1 باختبار ما إذا كانت الماكرو _DIRENT_HAVE_D_NAMLEN أو _DIRENT_HAVE_D_RECLEN أو _DIRENT_HAVE_D_OFF أو _DIRENT_HAVE_D_TYPE مُعرفة.

  الحقل .d_name
تعريف بنية dirent الموضح أعلاه مأخوذ من رؤوس glibc، ويُظهر الحقل .d_name بحجم ثابت.

تحذير: يجب على التطبيقات تجنب أي اعتماد على حجم الحقل .d_name. يُعرفه POSIX كـ char d_name[]، مصفوفة محارف بحجم غير محدد، مع NAME_MAX حرفًا على الأكثر قبل البايت الصفري الختامي ('\0').

يُشير POSIX.1 صراحةً إلى أن هذا الحقل لا ينبغي استخدامه كقيمة يسارية. يُلاحظ المعيار أيضًا أن استخدام sizeof(.d_name) غير صحيح؛ استخدم strlen(.d_name) بدلاً من ذلك. (على بعض الأنظمة، يُعرف هذا الحقل كـ char d_name[1]!) بالتبعية، استخدام sizeof(struct dirent) لالتقاط حجم السجل بما في ذلك حجم .d_name غير صحيح أيضًا.

لاحظ أنه بينما الاستدعاء

    fpathconf(fd, _PC_NAME_MAX)

يُرجع القيمة 255 لمعظم أنظمة الملفات، على بعض أنظمة الملفات (مثل CIFS، خوادم Windows SMB)، اسم الملف المنتهي بصفر الذي يُرجع (بشكل صحيح) في .d_name يمكن أن يتجاوز هذا الحجم فعليًا. في مثل هذه الحالات، سيحتوي الحقل .d_reclen على قيمة تتجاوز حجم بنية glibc dirent الموضحة أعلاه.

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

التاريخ
POSIX.1-2001، SVr4، 4.3BSD.

ملاحظات
يُفتح دفق الدليل باستخدام opendir(3).

الترتيب الذي تُقرأ به أسماء الملفات باستدعاءات متتالية لـ readdir() يعتمد على تطبيق نظام الملفات؛ من غير المحتمل أن تُرتب الأسماء بأي شكل.

انظر أيضًا
getdents(2), read(2), closedir(3), dirfd(3), ftw(3), offsetof(3), opendir(3), readdir_r(3), rewinddir(3), scandir(3), seekdir(3), telldir(3)

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

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

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