الاسم¶

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:

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