Ubuntu Manpages

الاسم

المكتبة

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

موجز

#include <sys/types.h>
#include <sys/stat.h>
#include <fts.h>
FTS *fts_open(char *const *path_argv, int options,
typeof(int (const FTSENT **, const FTSENT **))
                  *_Nullable compar);
FTSENT *fts_read(FTS *ftsp);
FTSENT *fts_children(FTS *ftsp, int instr);
int fts_set(FTS *ftsp, FTSENT *f, int instr);
int fts_close(FTS *ftsp);

الوصف

تُوفر دوال fts لاجتياز التسلسلات الهرمية للملفات. نظرة عامة بسيطة هي أن الدالة fts_open() تُرجع "مقبضًا" (من النوع FTS *) يشير إلى "دفق" تسلسل هرمي للملفات. يُمرر هذا المقبض بعد ذلك إلى دوال fts الأخرى. الدالة fts_read() تُرجع مؤشرًا إلى بنية تصف أحد الملفات في التسلسل الهرمي. الدالة fts_children() تُرجع مؤشرًا إلى قائمة مرتبطة من البنى، كل منها يصف أحد الملفات الموجودة في دليل في التسلسل الهرمي.

بشكل عام، تُزار الأدلة مرتين قابلتين للتمييز؛ بالترتيب المسبق (قبل زيارة أي من توابعها) وبالترتيب اللاحق (بعد زيارة جميع توابعها). تُزار الملفات مرة واحدة. من الممكن السير في التسلسل الهرمي "منطقيًا" (زيارة الملفات التي تشير إليها الروابط الرمزية) أو فيزيائيًا (زيارة الروابط الرمزية نفسها)، ترتيب السير في التسلسل الهرمي أو تقليم و/أو إعادة زيارة أجزاء من التسلسل الهرمي.

تُعرف بنيتان (وأنواع مرتبطة) في ملف التضمين <fts.h>. النوع الأول هو FTS، البنية التي تمثل التسلسل الهرمي للملفات نفسه. النوع الثاني هو FTSENT، البنية التي تمثل ملفًا في التسلسل الهرمي. عادةً، تُرجع بنية FTSENT لكل ملف في التسلسل الهرمي. في صفحة الدليل هذه، "ملف" و"بنية FTSENT" قابلان للتبادل بشكل عام.

تحتوي بنية FTSENT على حقول تصف ملفًا. تحتوي البنية على الأقل على الحقول التالية (توجد حقول إضافية ينبغي اعتبارها خاصة بالتنفيذ):


typedef struct _ftsent {
    unsigned short  fts_info;     /* أعلام لبنية FTSENT */
    char           *fts_accpath;  /* مسار الوصول */
    char           *fts_path;     /* مسار الجذر */
    short           fts_pathlen;  /* strlen(fts_path) +
                                     strlen(fts_name) */
    char           *fts_name;     /* اسم الملف */
    short           fts_namelen;  /* strlen(fts_name) */
    short           fts_level;    /* العمق (من -1 إلى N) */
    int             fts_errno;    /* رقم خطأ (errno) الملف */
    long            fts_number;   /* قيمة عددية محلية */
    void           *fts_pointer;  /* قيمة عنوان محلية */
    struct _ftsent *fts_parent;   /* الدليل الأب */
    struct _ftsent *fts_link;     /* بنية الملف التالية */
    struct _ftsent *fts_cycle;    /* بنية الحلقة التكرارية */
    struct stat    *fts_statp;    /* معلومات الدالة [l]stat(2) */
} FTSENT;

تُعرف هذه الحقول كما يلي:

إحدى القيم التالية التي تصف بنية FTSENT المُرجعة والملف الذي تمثله. باستثناء الأدلة بدون أخطاء (FTS_D)، جميع هذه الإدخالات نهائية، أي أنها لن تُعاد زيارتها، ولن تُزار أي من توابعها.
دليل يُزار بالترتيب المسبق.
دليل يُسبب دورة في الشجرة. (سيُملأ حقل fts_cycle لبنية FTSENT أيضًا.)
أي بنية FTSENT تمثل نوع ملف غير موصوف صراحةً بأحد قيم fts_info الأخرى.
دليل لا يمكن قراءته. هذا إرجاع خطأ، وسيُضبط حقل fts_errno للإشارة إلى سبب الخطأ.
ملف باسم "." أو ".." لم يُحدد كاسم ملف للدالة fts_open() (انظر FTS_SEEDOT).
دليل يُزار بترتيب لاحق. محتويات بنية FTSENT ستكون غير متغيرة عن وقت إرجاعها بترتيب سابق، أي مع ضبط حقل fts_info على FTS_D.
هذا إرجاع خطأ، وسيُضبط حقل fts_errno للإشارة إلى سبب الخطأ.
ملف عادي.
ملف لم تكن معلومات [l]stat(2) متوفرة له. محتويات حقل fts_statp غير معرفة. هذا إرجاع خطأ، وسيُضبط حقل fts_errno للإشارة إلى سبب الخطأ.
ملف لم تُطلب معلومات [l]stat(2) له. محتويات حقل fts_statp غير معرفة.
رابط رمزي.
رابط رمزي بهدف غير موجود. محتويات حقل fts_statp تشير إلى معلومات خصائص الملف للرابط الرمزي نفسه.
مسار للوصول إلى الملف من الدليل الحالي.
المسار النسبي للملف بالنسبة لجذر التجوال. يحتوي هذا المسار على المسار المُحدد للدالة fts_open() كبادئة.
مجموع أطوال السلاسل المحارف المُشار إليها بواسطة fts_path و fts_name.
اسم الملف.
طول سلسلة المحارف المُشار إليها بواسطة fts_name.
عمق التجوال، مُرقّم من -1 إلى N، حيث وُجد هذا الملف. هيكل FTSENT الذي يُمثل أصل نقطة البداية (أو الجذر) للتجوال مُرقّم بـ -1، وهيكل FTSENT للجذر نفسه مُرقّم بـ 0.
إذا أعادت fts_children() أو fts_read() هيكل FTSENT حقل fts_info فيه مُعيَّن إلى FTS_DNR أو FTS_ERR أو FTS_NS، فإن حقل fts_errno يحتوي على رقم الخطأ (أي قيمة errno) المُحدِّد للخطأ. وإلا، فإن محتويات حقل fts_errno غير مُعرَّفة.
هذا الحقل مُوفَّر لاستخدام برنامج التطبيق ولا تُعدِّله دوال fts. يُهيَّأ إلى 0.
هذا الحقل مُوفَّر لاستخدام برنامج التطبيق ولا تُعدِّله دوال fts. يُهيَّأ إلى NULL.
مؤشر إلى هيكل FTSENT يُشير إلى الملف في التسلسل الهرمي مباشرة فوق الملف الحالي، أي الدليل الذي ينتمي إليه هذا الملف. هيكل أصل لنقطة الدخول الأولية مُوفَّر أيضًا، ومع ذلك، فقط الحقول fts_level و fts_number و fts_pointer مضمونة أن تكون مُهيَّأة.
عند العودة من الدالة fts_children()، يُشير حقل fts_link إلى الهيكل التالي في القائمة المرتبطة المُنتهية بـ NULL لأعضاء الدليل. وإلا، فإن محتويات حقل fts_link غير مُعرَّفة.
إذا تسبب دليل في دورة في التراتبية (انظر FTS_DC)، إما بسبب رابط صلب بين دليلين، أو رابط رمزي يشير إلى دليل، فإن حقل fts_cycle في البنية سيشير إلى بنية FTSENT في التراتبية التي تشير إلى نفس الملف مثل بنية FTSENT الحالية. وإلا، فإن محتويات حقل fts_cycle غير معرفة.
مؤشر إلى معلومات [l]stat(2) للملف.

يُستخدم مخزن واحد لجميع مسارات جميع الملفات في تراتبية الملفات. لذلك، يُضمن أن حقلي fts_path و fts_accpath منتهيان بقيمة فارغة فقط للملف الذي أُعيد مؤخرًا بواسطة fts_read(). لاستخدام هذين الحقلين للإشارة إلى أي ملفات ممثلة ببنى FTSENT أخرى، سيتطلب تعديل مخزن المسار باستخدام المعلومات الموجودة في حقل fts_pathlen لتلك البنية FTSENT. يجب التراجع عن أي تعديلات من هذا القبيل قبل محاولة استدعاءات إضافية لـ fts_read(). حقل fts_name دائمًا منتهٍ بقيمة فارغة.

تأخذ دالة fts_open() مؤشرًا إلى مصفوفة من مؤشرات المحارف تسمي مسارًا واحدًا أو أكثر تشكل تراتبية ملفات منطقية ليتم اجتيازها. يجب إنهاء المصفوفة بمؤشر فارغ.

هناك عدد من الخيارات، يجب تحديد واحد منها على الأقل (إما FTS_LOGICAL أو FTS_PHYSICAL). تُختار الخيارات عن طريق إجراء عملية OR على القيم التالية:

يتسبب هذا الخيار في إرجاع إجراءات fts لبنى FTSENT لأهداف الروابط الرمزية بدلاً من الروابط الرمزية نفسها. إذا تم تعيين هذا الخيار، فإن الروابط الرمزية الوحيدة التي تُعاد بنى FTSENT منها إلى التطبيق هي تلك التي تشير إلى ملفات غير موجودة: يُحصل على حقل fts_statp عبر stat(2) مع الرجوع إلى lstat(2).
يتسبب هذا الخيار في إرجاع إجراءات fts لبنى FTSENT للروابط الرمزية نفسها بدلاً من الملفات الهدف التي تشير إليها. إذا تم تعيين هذا الخيار، تُعاد بنى FTSENT لجميع الروابط الرمزية في التراتبية إلى التطبيق: يُحصل على حقل fts_statp عبر lstat(2).
يتسبب هذا الخيار في اتباع أي رابط رمزي محدد كمسار جذر فورًا، كما لو كان عبر FTS_LOGICAL، بغض النظر عن الوضع الأساسي.
كتحسين للأداء، تغير دوال fts الدلائل أثناء سيرها في تراتبية الملفات. لهذا تأثير جانبي بأن التطبيق لا يمكنه الاعتماد على التواجد في أي دليل معين أثناء الاجتياز. يُوقف هذا الخيار هذا التحسين، ولن تغير دوال fts الدليل الحالي. لاحظ أنه لا ينبغي للتطبيقات نفسها تغيير دليلها الحالي ومحاولة الوصول إلى الملفات ما لم يتم تحديد FTS_NOCHDIR وتقديم أسماء مسارات مطلقة كوسائط لـ fts_open().
افتراضيًا، تشير بنى FTSENT المعادة إلى معلومات خصائص الملف (حقل fts_statp) لكل ملف تمت زيارته. يُخفف هذا الخيار هذا المطلب كتحسين للأداء، مما يسمح لدوال fts بتعيين حقل fts_info إلى FTS_NSOK وترك محتويات حقل fts_statp غير معرفة.
افتراضيًا، ما لم يتم تحديدها كوسائط مسار لـ fts_open()، يتم تجاهل أي ملفات مسماة "." أو ".." تُواجه في تراتبية الملفات. يتسبب هذا الخيار في إرجاع إجراءات fts لبنى FTSENT لها.
يمنع هذا الخيار fts من النزول إلى أدلة ذات رقم جهاز مختلف عن الملف الذي بدأ منه النزول.

يحدد المعامل compar() دالة معرفة من قبل المستخدم يمكن استخدامها لترتيب اجتياز التدرج الهرمي. تأخذ مؤشرين إلى مؤشرات لهياكل FTSENT كمعاملات ويجب أن تُرجع قيمة سالبة، صفر، أو قيمة موجبة للإشارة إلى ما إذا كان الملف المشار إليه بمعاملها الأول يأتي قبل، بأي ترتيب بالنسبة إلى، أو بعد الملف المشار إليه بمعاملها الثاني. لا يجوز أبدًا استخدام حقول fts_accpath و fts_path و fts_pathlen من هياكل FTSENT في هذه المقارنة. إذا كان حقل fts_info مضبوطًا على FTS_NS أو FTS_NSOK، فلا يجوز أيضًا استخدام حقل fts_statp. إذا كان معامل compar() هو NULL، فإن ترتيب اجتياز الدليل يكون بالترتيب المدرج في path_argv للمسارات الجذرية، وبالترتيب المدرج في الدليل لكل شيء آخر.

تُرجع الدالة fts_read() مؤشرًا إلى هيكل FTSENT يصف ملفًا في التدرج الهرمي. تُزار الأدلة (القابلة للقراءة والتي لا تسبب دورات) مرتين على الأقل، مرة بالترتيب المسبق ومرة بالترتيب اللاحق. تُزار جميع الملفات الأخرى مرة واحدة على الأقل. (قد تتسبب الروابط الثابتة بين الأدلة التي لا تسبب دورات أو الروابط الرمزية إلى روابط رمزية في زيارة الملفات أكثر من مرة، أو الأدلة أكثر من مرتين.)

إذا تم إرجاع جميع أعضاء التدرج الهرمي، تُرجع fts_read() NULL وتضبط errno على 0. إذا حدث خطأ غير مرتبط بملف في التدرج الهرمي، تُرجع fts_read() NULL وتضبط errno للإشارة إلى الخطأ. إذا حدث خطأ مرتبط بملف مُعاد، يُرجع مؤشر إلى هيكل FTSENT، وقد يكون errno مضبوطًا أو لا (انظر fts_info).

قد تُستبدل هياكل FTSENT التي تُرجعها fts_read() بعد استدعاء fts_close() على نفس دفق التدرج الهرمي للملف، أو بعد استدعاء fts_read() على نفس دفق التدرج الهرمي للملف ما لم تمثل ملفًا من نوع دليل، وفي هذه الحالة لن تُستبدل حتى بعد استدعاء fts_read() بعد إرجاع هيكل FTSENT بواسطة الدالة fts_read() بالترتيب اللاحق.

تُرجع الدالة fts_children() مؤشرًا إلى هيكل FTSENT يصف الإدخال الأول في قائمة مرتبطة منتهية بـ NULL من الملفات في الدليل الممثل بهيكل FTSENT الذي أُعيد مؤخرًا بواسطة fts_read(). تُربط القائمة من خلال حقل fts_link لهيكل FTSENT، وتُرتب بواسطة دالة المقارنة المحددة من قبل المستخدم، إن وجدت. ستعيد الاستدعاءات المتكررة لـ fts_children() إنشاء هذه القائمة المرتبطة.

كحالة خاصة، إذا لم تُستدع fts_read() بعد لتدرج هرمي، فستُرجع fts_children() مؤشرًا إلى الملفات في الدليل المنطقي المحدد لـ fts_open()، أي المعاملات المحددة لـ fts_open(). بخلاف ذلك، إذا كان هيكل FTSENT الذي أُعيد مؤخرًا بواسطة fts_read() ليس دليلًا يُزار بالترتيب المسبق، أو كان الدليل لا يحتوي على أي ملفات، تُرجع fts_children() NULL وتضبط errno على صفر. إذا حدث خطأ، تُرجع fts_children() NULL وتضبط errno للإشارة إلى الخطأ.

قد تُستبدل هياكل FTSENT التي تُرجعها fts_children() بعد استدعاء fts_children() أو fts_close() أو fts_read() على نفس دفق التدرج الهرمي للملف.

المعامل instr إما صفر أو القيمة التالية:

يلزم فقط أسماء الملفات. محتويات جميع الحقول في القائمة المرتبطة المعادة من الهياكل غير محددة باستثناء حقلي fts_name و fts_namelen.

تسمح الدالة fts_set() لتطبيق المستخدم بتحديد معالجة إضافية للملف f من دفق ftsp. تُرجع الدالة fts_set() 0 عند النجاح، و -1 إذا حدث خطأ.

المعامل instr إما 0 (بمعنى "لا تفعل شيئًا") أو إحدى القيم التالية:

أعد زيارة الملف؛ يمكن إعادة زيارة أي نوع ملف. ستعيد الاستدعاء التالي لـ fts_read() الملف المشار إليه. ستُعاد تهيئة حقلي fts_stat و fts_info من الهيكل في ذلك الوقت، لكن لن تُغير أي حقول أخرى. هذا الخيار ذو معنى فقط للملف الذي أُعيد مؤخرًا من fts_read(). الاستخدام العادي هو لزيارات الدليل بالترتيب اللاحق، حيث يتسبب في إعادة زيارة الدليل (بالترتيب المسبق واللاحق) بالإضافة إلى جميع فروعه.
يجب أن يكون الملف المُشار إليه رابطًا رمزيًا. إذا كان الملف المُشار إليه هو آخر ملف أُعيد بواسطة fts_read()، فإن الاستدعاء التالي لـ fts_read() يُعيد الملف مع إعادة تهيئة حقلي fts_info و fts_statp لتعكس هدف الرابط الرمزي بدلاً من الرابط الرمزي نفسه. إذا كان الملف واحدًا من تلك التي أُعيدت مؤخرًا بواسطة fts_children()، فإن حقلي fts_info و fts_statp في البنية، عند إعادتهما بواسطة fts_read()، سيعكسان هدف الرابط الرمزي بدلاً من الرابط الرمزي نفسه. في كلتا الحالتين، إذا لم يكن هدف الرابط الرمزي موجودًا، فستبقى حقول البنية المُعادة دون تغيير وسيُضبط حقل fts_info على FTS_SLNONE.
إذا كان هدف الرابط دليلاً، فسيتم إعادة الترتيب المسبق، متبوعًا بإعادة جميع فروعه، متبوعًا بإعادة ترتيب لاحق.
لا تُزار أي فروع لهذا الملف. قد يكون الملف واحدًا من تلك التي أُعيدت مؤخرًا بواسطة إما fts_children() أو fts_read().

تُغلق دالة fts_close() تدفق التسلسل الهرمي للملفات المُشار إليه بواسطة ftsp وتستعيد الدليل الحالي إلى الدليل الذي استُدعيت منه fts_open() لفتح ftsp. تُعيد دالة fts_close() 0 عند النجاح، و -1 في حالة حدوث خطأ.

الأخطاء

قد تفشل دالة fts_open() وتُضبط errno لأي من الأخطاء المُحددة لـ open(2) و malloc(3).

بالإضافة إلى ذلك، قد تفشل fts_open() وتُضبط errno كما يلي:

كان أي عنصر من path_argv سلسلة محارف فارغة.

قد تفشل دالة fts_close() وتُضبط errno لأي من الأخطاء المُحددة لـ chdir(2) و close(2).

قد تفشل الدالتان fts_read() و fts_children() وتُضبطان errno لأي من الأخطاء المُحددة لـ chdir(2)، malloc(3)، opendir(3)، readdir(3)، و [l]stat(2).

بالإضافة إلى ذلك، قد تفشل fts_children()، fts_open()، و fts_set() وتُضبط errno كما يلي:

كان options أو instr غير صالح.

السمات

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

الواجهة السمة القيمة
fts_open(), fts_set(), fts_close() سلامة الخيوط MT-Safe
fts_read(), fts_children() سلامة الخيوط غير آمن لتعدد الخيوط (MT-Unsafe)

المعايير

لا شيء.

التاريخ

glibc 2. 4.4BSD.

العلل

قبل glibc 2.23، جميع واجهات برمجة التطبيقات الموصوفة في صفحة الدليل هذه ليست آمنة عند ترجمة برنامج يستخدم واجهات برمجة تطبيقات LFS (مثلًا، عند الترجمة باستخدام -D_FILE_OFFSET_BITS=64).

انظر أيضًا

find(1)، chdir(2)، lstat(2)، stat(2)، ftw(3)، qsort(3)

ترجمة

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

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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