fts(3)

الاسم
fts، fts_open، fts_read، fts_children، fts_set، fts_close - اجتياز تسلسل هرمي للملفات

المكتبة
مكتبة سي المعيارية (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;

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

fts_info
    إحدى القيم التالية التي تصف بنية FTSENT المُرجعة والملف الذي تمثله. باستثناء الأدلة بدون أخطاء (FTS_D)، جميع هذه الإدخالات نهائية، أي أنها لن تُعاد زيارتها، ولن تُزار أي من توابعها.

    FTS_D
        دليل يُزار بالترتيب المسبق.

    FTS_DC
        دليل يُسبب دورة في الشجرة. (سيُملأ حقل fts_cycle لبنية FTSENT أيضًا.)

    FTS_DEFAULT
        أي بنية FTSENT تمثل نوع ملف غير موصوف صراحةً بأحد قيم fts_info الأخرى.

    FTS_DNR
        دليل لا يمكن قراءته. هذا إرجاع خطأ، وسيُضبط حقل fts_errno للإشارة إلى سبب الخطأ.

    FTS_DOT
        ملف باسم "." أو ".." لم يُحدد كاسم ملف للدالة fts_open() (انظر FTS_SEEDOT).

    FTS_DP
        دليل يُزار بترتيب لاحق. محتويات بنية FTSENT ستكون غير متغيرة عن وقت إرجاعها بترتيب سابق، أي مع ضبط حقل fts_info على FTS_D.

    FTS_ERR
        هذا إرجاع خطأ، وسيُضبط حقل fts_errno للإشارة إلى سبب الخطأ.

    FTS_F
        ملف عادي.

    FTS_NS
        ملف لم تكن معلومات [l]stat(2) متوفرة له. محتويات حقل fts_statp غير معرفة. هذا إرجاع خطأ، وسيُضبط حقل fts_errno للإشارة إلى سبب الخطأ.

    FTS_NSOK
        ملف لم تُطلب معلومات [l]stat(2) له. محتويات حقل fts_statp غير معرفة.

    FTS_SL
        رابط رمزي.

    FTS_SLNONE
        رابط رمزي بهدف غير موجود. محتويات حقل fts_statp تشير إلى معلومات خصائص الملف للرابط الرمزي نفسه.

fts_accpath
    مسار للوصول إلى الملف من الدليل الحالي.

fts_path
    المسار النسبي للملف بالنسبة لجذر التجوال. يحتوي هذا المسار على المسار المُحدد للدالة fts_open() كبادئة.

fts_pathlen
    مجموع أطوال السلاسل المحارف المُشار إليها بواسطة fts_path و fts_name.

fts_name
    اسم الملف.

fts_namelen
    طول سلسلة المحارف المُشار إليها بواسطة fts_name.

fts_level
    عمق التجوال، مُرقّم من -1 إلى N، حيث وُجد هذا الملف. هيكل FTSENT الذي يُمثل أصل نقطة البداية (أو الجذر) للتجوال مُرقّم بـ -1، وهيكل FTSENT للجذر نفسه مُرقّم بـ 0.

fts_errno
    إذا أعادت fts_children() أو fts_read() هيكل FTSENT حقل fts_info فيه مُعيَّن إلى FTS_DNR أو FTS_ERR أو FTS_NS، فإن حقل fts_errno يحتوي على رقم الخطأ (أي قيمة errno) المُحدِّد للخطأ. وإلا، فإن محتويات حقل fts_errno غير مُعرَّفة.

fts_number
    هذا الحقل مُوفَّر لاستخدام برنامج التطبيق ولا تُعدِّله دوال fts. يُهيَّأ إلى 0.

fts_pointer
    هذا الحقل مُوفَّر لاستخدام برنامج التطبيق ولا تُعدِّله دوال fts. يُهيَّأ إلى NULL.

fts_parent
    مؤشر إلى هيكل FTSENT يُشير إلى الملف في التسلسل الهرمي مباشرة فوق الملف الحالي، أي الدليل الذي ينتمي إليه هذا الملف. هيكل أصل لنقطة الدخول الأولية مُوفَّر أيضًا، ومع ذلك، فقط الحقول fts_level و fts_number و fts_pointer مضمونة أن تكون مُهيَّأة.

fts_link
    عند العودة من الدالة fts_children()، يُشير حقل fts_link إلى الهيكل التالي في القائمة المرتبطة المُنتهية بـ NULL لأعضاء الدليل. وإلا، فإن محتويات حقل fts_link غير مُعرَّفة.

fts_cycle
    إذا تسبب دليل في دورة في التراتبية (انظر FTS_DC)، إما بسبب رابط صلب بين دليلين، أو رابط رمزي يشير إلى دليل، فإن حقل fts_cycle في البنية سيشير إلى بنية FTSENT في التراتبية التي تشير إلى نفس الملف مثل بنية FTSENT الحالية. وإلا، فإن محتويات حقل fts_cycle غير معرفة.

fts_statp
    مؤشر إلى معلومات [l]stat(2) للملف.

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

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

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

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

FTS_PHYSICAL
    يتسبب هذا الخيار في إرجاع إجراءات fts لبنى FTSENT للروابط الرمزية نفسها بدلاً من الملفات الهدف التي تشير إليها. إذا تم تعيين هذا الخيار، تُعاد بنى FTSENT لجميع الروابط الرمزية في التراتبية إلى التطبيق: يُحصل على حقل fts_statp عبر lstat(2).

FTS_COMFOLLOW
    يتسبب هذا الخيار في اتباع أي رابط رمزي محدد كمسار جذر فورًا، كما لو كان عبر FTS_LOGICAL، بغض النظر عن الوضع الأساسي.

FTS_NOCHDIR
    كتحسين للأداء، تغير دوال fts الدلائل أثناء سيرها في تراتبية الملفات. لهذا تأثير جانبي بأن التطبيق لا يمكنه الاعتماد على التواجد في أي دليل معين أثناء الاجتياز. يُوقف هذا الخيار هذا التحسين، ولن تغير دوال fts الدليل الحالي. لاحظ أنه لا ينبغي للتطبيقات نفسها تغيير دليلها الحالي ومحاولة الوصول إلى الملفات ما لم يتم تحديد FTS_NOCHDIR وتقديم أسماء مسارات مطلقة كوسائط لـ fts_open().

FTS_NOSTAT
    افتراضيًا، تشير بنى FTSENT المعادة إلى معلومات خصائص الملف (حقل fts_statp) لكل ملف تمت زيارته. يُخفف هذا الخيار هذا المطلب كتحسين للأداء، مما يسمح لدوال fts بتعيين حقل fts_info إلى FTS_NSOK وترك محتويات حقل fts_statp غير معرفة.

FTS_SEEDOT
    افتراضيًا، ما لم يتم تحديدها كوسائط مسار لـ fts_open()، يتم تجاهل أي ملفات مسماة "." أو ".." تُواجه في تراتبية الملفات. يتسبب هذا الخيار في إرجاع إجراءات fts لبنى FTSENT لها.

FTS_XDEV
    يمنع هذا الخيار fts من النزول إلى أدلة ذات رقم جهاز مختلف عن الملف الذي بدأ منه النزول.

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

  fts_read()
تُرجع الدالة 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()
تُرجع الدالة 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_NAMEONLY
    يلزم فقط أسماء الملفات. محتويات جميع الحقول في القائمة المرتبطة المعادة من الهياكل غير محددة باستثناء حقلي fts_name و fts_namelen.

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

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

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

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

    إذا كان هدف الرابط دليلاً، فسيتم إعادة الترتيب المسبق، متبوعًا بإعادة جميع فروعه، متبوعًا بإعادة ترتيب لاحق.

FTS_SKIP
    لا تُزار أي فروع لهذا الملف. قد يكون الملف واحدًا من تلك التي أُعيدت مؤخرًا بواسطة إما fts_children() أو fts_read().

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

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

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

ENOENT
    كان أي عنصر من 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 كما يلي:

EINVAL
    كان 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 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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