.\" -*- coding: UTF-8 -*- '\" t .\" Copyright 1999, Andries E. Brouwer .\" Copyright 2006, Justin Pryzby .\" Copyright 2006, Michael Kerrisk .\" Copyright, the authors of the Linux man-pages project .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH ftw 3 "8 فبراير 2026" "صفحات دليل لينكس 6.18" .SH الاسم ftw, nftw \- التجوال في شجرة الملفات .SH المكتبة مكتبة سي المعيارية (\fIlibc\fP،\ \fI\-lc\fP) .SH موجز .nf \fB#include \fP .P \fBint nftw(const char *\fP\fIdirpath\fP\fB,\fP \fB typeof(int (const char *\fP\fIfpath\fP\fB, const struct stat *\fP\fIsb,\fP \fB int \fP\fItypeflag\fP\fB, struct FTW *\fP\fIftwbuf\fP\fB))\fP \fB *\fP\fIfn,\fP \fB int \fP\fInopenfd\fP\fB, int \fP\fIflags\fP\fB);\fP .P \fB[[deprecated]]\fP \fBint ftw(const char *\fP\fIdirpath\fP\fB,\fP \fB typeof(int (const char *\fP\fIfpath\fP\fB, const struct stat *\fP\fIsb\fP\fB,\fP \fB int \fP\fItypeflag\fP\fB))\fP \fB *\fP\fIfn,\fP \fB int \fP\fInopenfd\fP\fB);\fP .fi .P .RS -4 متطلبات ماكروات اختبار الميزات لـ glibc (انظر \fBfeature_test_macros\fP(7)): .RE .P \fBnftw\fP(): .nf _XOPEN_SOURCE >= 500 .fi .SH الوصف \fBnftw\fP() يتجول في شجرة الدليل الموجودة تحت الدليل \fIdirpath\fP، ويستدعي \fIfn\fP() مرة واحدة لكل مدخل في الشجرة. مبدئيًا، تُعالج الدلائل قبل الملفات والدلائل الفرعية التي تحتويها (اجتياز بالترتيب المسبق). .P لتجنب استهلاك كل واصفات الملفات لعملية الاستدعاء، يُحدد \fInopenfd\fP الحد الأقصى لعدد الدلائل التي سيبقيها \fBnftw\fP() مفتوحة في وقت واحد. عندما يتجاوز عمق البحث هذا، يصبح \fBnftw\fP() أبطأ لأنه يجب إغلاق الدلائل وإعادة فتحها. يستخدم \fBnftw\fP() واصف ملف واحد على الأكثر لكل مستوى في شجرة الدليل. .P لكل مدخل يُوجد في الشجرة، يستدعي \fBnftw\fP() \fIfn\fP() بأربع وسائط: \fIfpath\fP و \fIsb\fP و \fItypeflag\fP و \fIftwbuf\fP. \fIfpath\fP هو اسم مسار المدخل، ويُعبر عنه إما كاسم مسار نسبي لدليل العمل الحالي لعملية الاستدعاء وقت استدعاء \fBnftw\fP()، إذا عُبر عن \fIdirpath\fP كاسم مسار نسبي، أو كاسم مسار مطلق، إذا عُبر عن \fIdirpath\fP كاسم مسار مطلق. \fIsb\fP هو مؤشر لبنية \fIstat\fP التي أرجعها استدعاء \fBstat\fP(2) لـ \fIfpath\fP. .P الوسيطة \fItypeflag\fP الممررة إلى \fIfn\fP() هي عدد صحيح له إحدى القيم التالية: .TP \fBFTW_F\fP \fIfpath\fP هو ملف عادي. .TP \fBFTW_D\fP \fIfpath\fP هو دليل. .TP \fBFTW_DNR\fP \fIfpath\fP هو دليل لا يمكن قراءته. .TP \fBFTW_DP\fP \fIfpath\fP هو دليل، وحدد \fBFTW_DEPTH\fP في \fIflags\fP. (إذا لم يُحدد \fBFTW_DEPTH\fP في \fIflags\fP، فستُزار الدلائل دائمًا مع تعيين \fItypeflag\fP إلى \fBFTW_D\fP.) عُولجت جميع الملفات والدلائل الفرعية داخل \fIfpath\fP. .TP \fBFTW_NS\fP فشل استدعاء \fBstat\fP(2) على \fIfpath\fP، وهو ليس رابطًا رمزيًا. السبب المحتمل لذلك هو أن المستدعي كان لديه إذن قراءة على الدليل الأب، بحيث يمكن رؤية اسم الملف \fIfpath\fP، ولكن لم يكن لديه إذن تنفيذ، بحيث لا يمكن الوصول إلى الملف لـ \fBstat\fP(2). محتويات المخزن المؤقت المشار إليه بواسطة \fIsb\fP غير محددة. .TP \fBFTW_SL\fP .\" To obtain the definition of this constant from .\" .IR , .\" either .\" .B _BSD_SOURCE .\" must be defined, or .\" .BR _XOPEN_SOURCE .\" must be defined with a value of 500 or more. \fIfpath\fP هو رابط رمزي، ووُضع \fBFTW_PHYS\fP في \fIflags\fP. .TP \fBFTW_SLN\fP \fIfpath\fP هو رابط رمزي يشير إلى ملف غير موجود. (يحدث هذا فقط إذا لم يُضبط \fBFTW_PHYS\fP.) في هذه الحالة، تحتوي الوسيطة \fIsb\fP الممررة إلى \fIfn\fP() على معلومات أُعيدت بتنفيذ \fBlstat\fP(2) على الرابط الرمزي "المتدلي". (لكن انظر BUGS.) .P الوسيطة الرابعة (\fIftwbuf\fP) التي يوفرها \fBnftw\fP() عند استدعاء \fIfn\fP() هي مؤشر لبنية من النوع \fIFTW\fP: .P .in +4n .EX struct FTW { int base; int level; }; .EE .in .P \fIbase\fP هو إزاحة اسم الملف (أي مكون الاسم الأساسي) في اسم المسار المعطى في \fIfpath\fP. \fIlevel\fP هو عمق \fIfpath\fP في شجرة الدليل، نسبة إلى جذر الشجرة (\fIdirpath\fP، الذي له عمق 0). .P لإيقاف التجوال في الشجرة، تُرجع \fIfn\fP() قيمة غير صفرية؛ ستصبح هذه القيمة القيمة المُعادة من \fBnftw\fP(). طالما تُرجع \fIfn\fP() 0، سيستمر \fBnftw\fP() إما حتى يجتاز الشجرة بأكملها، وفي هذه الحالة سيعيد صفرًا، أو حتى يواجه خطأ (مثل فشل \fBmalloc\fP(3))، وفي هذه الحالة سيعيد \-1. .P لأن \fBnftw\fP() يستخدم بنى بيانات ديناميكية، الطريقة الآمنة الوحيدة للخروج من تجوال الشجرة هي إعادة قيمة غير صفرية من \fIfn\fP(). للسماح لإشارة بإنهاء التجوال دون التسبب بتسرب ذاكرة، اجعل المعالج يضبط علمًا عامًا يُفحص بواسطة \fIfn\fP(). \fIلا\fP تستخدم \fBlongjmp\fP(3) ما لم يكن البرنامج على وشك الإنهاء. .P تُشكل الوسيطة \fIflags\fP الخاصة بـ \fBnftw\fP() بعملية OR على صفر أو أكثر من الأعلام التالية: .TP \fBFTW_ACTIONRETVAL\fP (منذ glibc 2.3.3) إذا ضُبط هذا العلم الخاص بـ glibc، فإن \fBnftw\fP() يعالج القيمة المُعادة من \fIfn\fP() بشكل مختلف. يجب أن تُرجع \fIfn\fP() إحدى القيم التالية: .RS .TP \fBFTW_CONTINUE\fP يأمر \fBnftw\fP() بالاستمرار بشكل طبيعي. .TP \fBFTW_SKIP_SIBLINGS\fP .\" If \f[B]FTW_DEPTH\f[] .\" is set, the entry's parent directory is processed next (with .\" \f[I]flag\f[] set to \f[B]FTW_DP\f[]). إذا أعادت \fIfn\fP() هذه القيمة، فسيُتجاوز عن أشقاء المدخل الحالي، ويستمر المعالجة في الدليل الأب. .TP \fBFTW_SKIP_SUBTREE\fP إذا استُدعيت \fIfn\fP() بمدخل هو دليل (\fItypeflag\fP هو \fBFTW_D\fP)، ستمنع قيمة الإرجاع هذه تمرير الكائنات داخل ذلك الدليل كوسيطات إلى \fIfn\fP(). يستمر \fBnftw\fP() في المعالجة مع الشقيق التالي للدليل. .TP \fBFTW_STOP\fP يسبب إرجاع \fBnftw\fP() فورًا بقيمة الإرجاع \fBFTW_STOP\fP. .P قد تُربط قيم إرجاع أخرى بإجراءات جديدة في المستقبل؛ يجب ألا تُرجع \fIfn\fP() قيمًا غير تلك المذكورة أعلاه. .P يجب تعريف كلية اختبار الميزة \fB_GNU_SOURCE\fP (قبل تضمين \fIأي\fP ملفات رأس) للحصول على تعريف \fBFTW_ACTIONRETVAL\fP من \fI\fP. .RE .TP \fBFTW_CHDIR\fP إذا ضُبط، يُنفذ \fBchdir\fP(2) إلى كل دليل قبل معالجة محتوياته. هذا مفيد إذا احتاج البرنامج لأداء إجراء في الدليل الذي يوجد فيه \fIfpath\fP. (تحديد هذه العلامة لا يؤثر على اسم المسار المُمرر في وسيط \fIfpath\fP للدالة \fIfn\fP.) .TP \fBFTW_DEPTH\fP إذا ضُبط، يُنفذ اجتياز بعدي، أي تُستدعى \fIfn\fP() للدليل نفسه \fIبعد\fP معالجة محتويات الدليل وأدلته الفرعية. (مبدئيًا، يُعالج كل دليل \fIقبل\fP محتوياته.) .TP \fBFTW_MOUNT\fP إذا ضُبط، يبقى داخل نفس نظام الملفات (أي لا يعبر نقاط الوصل). .TP \fBFTW_PHYS\fP إذا ضُبط، لا يتبع الروابط الرمزية. (هذا ما تريده.) إذا لم يُضبط، تُتبع الروابط الرمزية، لكن لا يُبلغ عن أي ملف مرتين. .IP إذا لم يُضبط \fBFTW_PHYS\fP، لكن ضُبط \fBFTW_DEPTH\fP، فلا تُستدعى الدالة \fIfn\fP() أبدًا لدليل سيكون سليلًا لنفسه. .SS ftw() \fBftw\fP() دالة أقدم تقدم مجموعة فرعية من وظائف \fBnftw\fP(). الاختلافات البارزة كما يلي: .IP \[bu] 3 \fBftw\fP() ليس لها وسيط \fIflags\fP. تتصرف بنفس الطريقة عندما تُستدعى \fBnftw\fP() مع تحديد \fIflags\fP كصفر. .IP \[bu] دالة الاستدعاء، \fIfn\fP()، لا تُزود بوسيط رابع. .IP \[bu] نطاق القيم المُمررة عبر وسيط \fItypeflag\fP المُزود لـ \fIfn\fP() أصغر: فقط \fBFTW_F\fP، \fBFTW_D\fP، \fBFTW_DNR\fP، \fBFTW_NS\fP، و (ربما) \fBFTW_SL\fP. .SH "قيمة الإرجاع" ترجع هذه الدوال 0 عند النجاح، و \-1 إذا حدث خطأ. .P إذا أرجع \fIfn\fP() قيمة غير صفرية، يُنهى اجتياز الشجرة وتُرجع القيمة التي أرجعها \fIfn\fP() كنتيجة لـ \fBftw\fP() أو \fBnftw\fP(). .P إذا استُدعيت \fBnftw\fP() مع علامة \fBFTW_ACTIONRETVAL\fP، فإن القيمة غير الصفرية الوحيدة التي يجب أن تستخدمها \fIfn\fP() لإنهاء اجتياز الشجرة هي \fBFTW_STOP\fP، وتُرجع تلك القيمة كنتيجة لـ \fBnftw\fP(). .SH السمات للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر \fBattributes\fP(7). .TS allbox; lbx lb lb l l l. الواجهة السمة القيمة T{ .na .nh \fBnftw\fP() T} سلامة الخيوط MT\-Safe cwd T{ .na .nh \fBftw\fP() T} سلامة الخيوط MT\-Safe .TE .SH الإصدارات في بعض التطبيقات (مثل glibc)، لن تستخدم \fBftw\fP() أبدًا \fBFTW_SL\fP؛ في أنظمة أخرى، يحدث \fBFTW_SL\fP فقط للروابط الرمزية التي لا تشير إلى ملف موجود؛ وفي أنظمة أخرى، ستستخدم \fBftw\fP() \fBFTW_SL\fP لكل رابط رمزي. إذا كان \fIfpath\fP رابطًا رمزيًا وفشل \fBstat\fP(2)، ينص POSIX.1\-2008 على أنه غير محدد ما إذا كان \fBFTW_NS\fP أو \fBFTW_SL\fP يُمرر في \fItypeflag\fP. للحصول على نتائج قابلة للتنبؤ، استخدم \fBnftw\fP(). .SH المعايير POSIX.1\-2008. .SH التاريخ .TP \fBftw\fP() POSIX.1\-2001, SVr4, SUSv1. يُصنف POSIX.1\-2008 هذه الدالة على أنها مهملة. .TP \fBnftw\fP() glibc 2.1. POSIX.1\-2001, SUSv1. .TP \fBFTW_SL\fP POSIX.1\-2001, SUSv1. .SH ملاحظات يلاحظ POSIX.1\-2008 أن النتائج غير محددة إذا لم يحافظ \fIfn\fP على دليل العمل الحالي. .SH العلل .\" https://bugzilla.redhat.com/show_bug.cgi?id=1422736 .\" http://austingroupbugs.net/view.php?id=1121 .\" glibc commit 6ba205b2c35e3e024c8c12d2ee1b73363e84da87 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=23501 وفقًا لـ POSIX.1\-2008، عندما يحتوي معامل \fItypeflag\fP الممرر إلى \fIfn\fP() على \fBFTW_SLN\fP، يجب أن تحتوي الخبيئة المشار إليها بواسطة \fIsb\fP على معلومات حول الرابط الرمزي المعلق (التي حُصل عليها باستدعاء \fBlstat\fP(2) على الرابط). اتبعت إصدارات glibc المبكرة مواصفات POSIX بشكل صحيح في هذه النقطة. ومع ذلك، نتيجة لانحدار أُدخل في glibc 2.4، كانت محتويات الخبيئة المشار إليها بواسطة \fIsb\fP غير محددة عندما يُمرر \fBFTW_SLN\fP في \fItypeflag\fP. (بشكل أكثر دقة، تُركت محتويات الخبيئة دون تغيير في هذه الحالة.) أُصلح هذا الانحدار في النهاية في glibc 2.30، بحيث يتبع تطبيق glibc (مرة أخرى) مواصفات POSIX. .SH أمثلة يجتاز البرنامج التالي شجرة الدليل تحت المسار المسمى في وسيط سطر الأوامر الأول، أو تحت الدليل الحالي إذا لم يُقدم وسيط. يعرض معلومات متنوعة عن كل ملف. يمكن استخدام وسيط سطر الأوامر الثاني لتحديد محارف تتحكم في القيمة المسندة إلى وسيط \fIflags\fP عند استدعاء \fBnftw\fP(). .SS "مصدر البرنامج" .\" SRC BEGIN (ftw.c) \& .EX #define _XOPEN_SOURCE 500 #include #include #include #include #include \& static int display_info(const char *fpath, const struct stat *sb, int tflag, struct FTW *ftwbuf) { printf("%\-3s %2d ", (tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" : (tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? "f" : (tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" : (tflag == FTW_SLN) ? "sln" : "???", ftwbuf\->level); \& if (tflag == FTW_NS) printf("\-\-\-\-\-\-\-"); else printf("%7jd", (intmax_t) sb\->st_size); \& printf(" %\-40s %d %s\[rs]n", fpath, ftwbuf\->base, fpath + ftwbuf\->base); \& return 0; /* لإخبار nftw() بالاستمرار */ } \& int main(int argc, char *argv[]) { int flags = 0; \& if (argc > 2 && strchr(argv[2], \[aq]d\[aq]) != NULL) flags |= FTW_DEPTH; if (argc > 2 && strchr(argv[2], \[aq]p\[aq]) != NULL) flags |= FTW_PHYS; \& if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags) == \-1) { perror("nftw"); exit(EXIT_FAILURE); } \& exit(EXIT_SUCCESS); } .EE .\" SRC END .SH "انظر أيضًا" \fBstat\fP(2), \fBfts\fP(3), \fBreaddir\fP(3) .PP .SH ترجمة تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي . .PP هذه الترجمة هي وثيقة مجانية؛ راجع .UR https://www.gnu.org/licenses/gpl-3.0.html رخصة جنو العامة الإصدار 3 .UE أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات. .PP إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: .MT kde-l10n-ar@kde.org .ME .