الاسم¶

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 للملف.

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:

حاليًا، بعض أنظمة الملفات فقط (من بينها: 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).

في مواصفات 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 مُعرّفة.

fpathconf(fd, _PC_NAME_MAX)

المعايير¶

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 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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