Scroll to navigation

fanotify_mark(2) System Calls Manual fanotify_mark(2)

الاسم

fanotify_mark - إضافة علامة fanotify على كائن نظام ملفات، أو إزالتها، أو تعديلها

المكتبة

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

موجز

#include <sys/fanotify.h>
int fanotify_mark(int fanotify_fd, unsigned int flags,
                  uint64_t mask, int dirfd,
                  const char *_Nullable pathname);

الوصف

للحصول على نظرة عامة حول واجهة برمجة تطبيقات fanotify، راجع fanotify(7).

تضيف fanotify_mark() علامة fanotify على كائن نظام ملفات، أو تزيلها، أو تعدلها. يجب أن يمتلك المستدعِي إذن القراءة على كائن نظام الملفات المراد وسمه.

المعطى fanotify_fd هو واصف ملف أعادته الدالة fanotify_init(2).

flags هو قناع بتات يصف التعديل المراد تنفيذه. يجب أن يتضمن قيمة واحدة بالضبط من القيم التالية:

ستُضاف الأحداث في mask إلى قناع العلامة (أو إلى قناع التجاهل). يجب ألا يكون mask فارغًا وإلا سيحدث الخطأ EINVAL.
ستُزال الأحداث في المعطى mask من قناع العلامة (أو من قناع التجاهل). يجب ألا يكون mask فارغًا وإلا سيحدث الخطأ EINVAL.
إزالة إما جميع العلامات لأنظمة الملفات، أو جميع العلامات للوصلات، أو جميع العلامات للأدلة والملفات من مجموعة fanotify. إذا احتوت flags على FAN_MARK_MOUNT، تُزال جميع العلامات للوصلات من المجموعة. إذا احتوت flags على FAN_MARK_FILESYSTEM، تُزال جميع العلامات لأنظمة الملفات من المجموعة. بخلاف ذلك، تُزال جميع العلامات للأدلة والملفات. لا يمكن استخدام أي راية أخرى مع FAN_MARK_FLUSH، باستثناء راية واحدة كحد أقصى من الرايتين FAN_MARK_MOUNT أو FAN_MARK_FILESYSTEM. يُتجاهل القناع mask_.

إذا لم تُحدد أي من القيم أعلاه، أو حُدد أكثر من واحدة، سيفشل الاستدعاء بالخطأ EINVAL.

بالإضافة إلى ذلك، يمكن دمج صفر أو أكثر من القيم التالية مع flags باستخدام العملية المنطقية OR:

إذا كان pathname رابطًا رمزيًا، فاسم الرابط نفسه بدلاً من الملف الذي يشير إليه. (بشكل مبدئي، تتبع fanotify_mark() الرابط pathname إذا كان رابطًا رمزيًا.)
إذا لم يكن كائن نظام الملفات المراد وسمه دليلاً، فسيُرفع الخطأ ENOTDIR.
وسم الوصلة المحددة بواسطة pathname. إذا لم يكن pathname نقطة وصل بحد ذاته، فستُوسم الوصلة التي تحتوي على pathname. ستُراقب جميع الأدلة، والأدلة الفرعية، والملفات الموجودة في الوصلة. لا يمكن تقديم الأحداث التي تتطلب تعريف كائنات نظام الملفات بواسطة مقابض الملفات، مثل FAN_CREATE و FAN_ATTRIB و FAN_MOVE و FAN_DELETE_SELF، كقناع mask_ عندما تحتوي flags على FAN_MARK_MOUNT. ستؤدي محاولة القيام بذلك إلى إرجاع الخطأ EINVAL. يتطلب استخدام هذه الراية قدرة CAP_SYS_ADMIN.
وسم نظام الملفات المحدد بواسطة pathname. سيُوسم نظام الملفات الذي يحتوي على pathname. ستُراقب جميع الملفات والأدلة الموجودة في نظام الملفات من أي نقطة وصل. يتطلب استخدام هذه الراية قدرة CAP_SYS_ADMIN.
ستُضاف الأحداث في mask إلى قناع التجاهل أو تُزال منه.لاحظ أن العلمين FAN_ONDIR و FAN_EVENT_ON_CHILD ليس لهما أي تأثير عند تقديمهما مع هذا العلم. إن تأثير ضبط العلمين FAN_ONDIR و FAN_EVENT_ON_CHILD في قناع العلامة على الأحداث المضبوطة في قناع التجاهل غير محدد ويعتمد على إصدار نواة لينكس.تحديداً، قبل لينكس 5.9، لم يكن ضبط قناع علامة على ملف وعلامة بقناع تجاهل على دليله الأب يؤدي إلى تجاهل الأحداث على الملف، بغض النظر عن علم FAN_EVENT_ON_CHILD في قناع علامة الدليل الأب. وعند تحديث قناع التجاهل بالعلم FAN_MARK_IGNORED_MASK على علامة حُدثت سابقاً بالعلم FAN_MARK_IGNORE، يفشل التحديث بالخطأ B.
لهذا العلم تأثير مشابه لضبط العلم FAN_MARK_IGNORED_MASK. ستُضاف الأحداث في I إلى قناع التجاهل أو تُزال منه. وعلى عكس العلم FAN_MARK_IGNORED_MASK، فإن هذا العلم يجعل العلمين FAN_ONDIR و FAN_EVENT_ON_CHILD يسريان على قناع التجاهل. تحديداً، ما لم يُضبط العلم FAN_ONDIR مع FAN_MARK_IGNORE، فلن تُتجاهل الأحداث على الأدلة. وإذا ضُبط العلم FAN_EVENT_ON_CHILD مع FAN_MARK_IGNORE، فستُتجاهل الأحداث على الأبناء. على سبيل المثال، علامة على دليل بمزيج من قناع به حدث FAN_CREATE وعلم FAN_ONDIR وقناع تجاهل به حدث FAN_CREATE وبدون علم FAN_ONDIR، ستؤدي إلى الحصول فقط على أحداث إنشاء الأدلة الفرعية. عند استخدام العلم FAN_MARK_IGNORE للإضافة إلى قناع تجاهل لوصل أو نظام ملفات أو علامة inode لدليل، يجب تحديد العلم FAN_MARK_IGNORED_SURV_MODIFY. سيؤدي الفشل في القيام بذلك إلى الخطأ EINVAL أو EISDIR.
يجب أن يبقى قناع التجاهل بعد أحداث التعديل. إذا لم يُضبط هذا العلم، سيُمسح قناع التجاهل عند وقوع حدث تعديل على الكائن الموشوم. يُستخدم حذف هذا العلم عادةً لكبح الأحداث (مثل FAN_OPEN) لملف معين حتى يُعدل محتوى ذلك الملف. من غير المفيد كبح الأحداث على نظام ملفات كامل أو وصل أو كافة الملفات داخل دليل حتى يُعدل محتوى ملف ما؛ ولهذا السبب، يتطلب العلم FAN_MARK_IGNORE وجود العلم FAN_MARK_IGNORED_SURV_MODIFY على علامات الوصل أو أنظمة الملفات أو علامات inode للأدلة. لا يمكن إزالة هذا العلم من العلامة بمجرد ضبطه. وعند تحديث قناع التجاهل بدون هذا العلم على علامة حُدثت سابقاً بالأعلام FAN_MARK_IGNORE و FAN_MARK_IGNORED_SURV_MODIFY، سيفشل التحديث بالخطأ EEXIST.
هذا مرادف لـ (FAN_MARK_IGNORE|FAN_MARK_IGNORED_SURV_MODIFY).
عند إنشاء علامة inode بهذا العلم، لن يُثبّت كائن inode في خبيئة الـ inode، مما يسمح بطرد كائن inode من الخبيئة عندما يكون ضغط الذاكرة على النظام مرتفعاً. يؤدي طرد كائن inode إلى فقدان العلامة القابلة للطرد أيضًا. وعند تحديث قناع علامة inode قابلة للطرد دون استخدام العلم FAN_MARK_EVICTABLE، يُثبّت الـ inode الموشوم في خبيئة الـ inode وتصبح العلامة غير قابلة للطرد. وعند تحديث قناع علامة inode غير قابلة للطرد بالعلم FAN_MARK_EVICTABLE، تظل العلامة غير قابلة للطرد ويفشل التحديث بالخطأ EEXIST. الوصلات وأنظمة الملفات ليست كائنات قابلة للطرد، لذا فإن محاولة إنشاء علامة وصل أو نظام ملفات بالعلم FAN_MARK_EVICTABLE ستؤدي إلى الخطأ EINVAL. على سبيل المثال، يمكن استخدام علامات inode بالاشتراك مع علامات الوصل لتقليل كمية الأحداث من المسارات غير المهمة؛ يقرأ مستمع الأحداث الحدث، ويتحقق مما إذا كان المسار المذكور فيه مهماً، وإذا لم يكن كذلك، يضع المستمع علامة بقناع تجاهل على الدليل. تسمح علامات inode القابلة للطرد باستخدام هذه الطريقة لعدد كبير من الأدلة دون القلق من تثبيت كافة الـ inodes واستنفاد ذاكرة النظام.

يحدد mask الأحداث التي يجب الاستماع إليها (أو التي يجب تجاهلها). وهو قناع بتات يتكون من القيم التالية:

إنشاء حدث عند الوصول إلى ملف أو دليل (قراءة) (لكن انظر BUGS).
إنشاء حدث عند تعديل ملف (كتابة).
إنشاء حدث عند إغلاق ملف قابل للكتابة.
إنشاء حدث عند إغلاق ملف أو دليل للقراءة فقط.
إنشاء حدث عند فتح ملف أو دليل.
إنشاء حدث عند فتح ملف بقصد تنفيذه. انظر NOTES لمزيد من التفاصيل.
إنشاء حدث عند تغير البيانات الوصفية لملف أو دليل. يتطلب ذلك مجموعة fanotify تميز كائنات نظام الملفات عبر مقابض الملفات.
إنشاء حدث عند إنشاء ملف أو دليل في دليل أب موشوم. يتطلب ذلك مجموعة fanotify تميز كائنات نظام الملفات عبر مقابض الملفات.
إنشاء حدث عند حذف ملف أو دليل في دليل أب موشوم. يتطلب ذلك مجموعة fanotify تميز كائنات نظام الملفات عبر مقابض الملفات.
إنشاء حدث عند حذف ملف أو دليل موشوم نفسه. يتطلب ذلك مجموعة fanotify تميز كائنات نظام الملفات عبر مقابض الملفات.
إنشاء حدث عند اكتشاف خطأ في نظام الملفات يؤدي إلى بيانات وصفية غير متسقة لنظام الملفات. يُعاد سجل معلومات إضافي من النوع FAN_EVENT_INFO_TYPE_ERROR لكل حدث في ذاكرة القراءة الوسيطة. مطلوب مجموعة fanotify تُعرف كائنات نظام الملفات عبر مقابض الملفات.
تعتمد الأحداث من هذا النوع على دعم نظام الملفات الأساسي. في وقت كتابة هذا الدليل، يبلغ نظام الملفات ext4 فقط عن أحداث FAN_FS_ERROR.
انظر fanotify(7) لتفاصيل إضافية.
إنشاء حدث عند نقل ملف أو دليل من دليل أب موشوم. يتطلب ذلك مجموعة fanotify تميز كائنات نظام الملفات عبر مقابض الملفات.
إنشاء حدث عند نقل ملف أو دليل إلى دليل أب موشوم. يتطلب ذلك مجموعة fanotify تميز كائنات نظام الملفات عبر مقابض الملفات.
يحتوي هذا الحدث على نفس المعلومات التي يوفرها الحدثان FAN_MOVED_FROM و FAN_MOVED_TO، ومع ذلك فإنه يُمثَّل بحدث واحد يحتوي على سجلين من المعلومات كحد أقصى. يتطلب ذلك مجموعة fanotify تميز كائنات نظام الملفات عبر مقابض الملفات. وإذا لم يكن كائن نظام الملفات المراد وسمه دليلاً، فسيُرفع الخطأ ENOTDIR.
إنشاء حدث عند نقل ملف أو دليل موشوم نفسه. يتطلب ذلك مجموعة fanotify تميز كائنات نظام الملفات عبر مقابض الملفات.
إنشاء حدث عند طلب إذن لفتح ملف أو دليل. يتطلب ذلك واصف ملف fanotify أُنشئ باستخدام FAN_CLASS_PRE_CONTENT أو FAN_CLASS_CONTENT.
إنشاء حدث عند طلب إذن لفتح ملف للتنفيذ. يتطلب ذلك واصف ملف fanotify أُنشئ باستخدام FAN_CLASS_PRE_CONTENT أو FAN_CLASS_CONTENT. انظر NOTES لمزيد من التفاصيل.
إنشاء حدث عند طلب إذن لقراءة ملف أو دليل. يتطلب ذلك واصف ملف fanotify أُنشئ باستخدام FAN_CLASS_PRE_CONTENT أو FAN_CLASS_CONTENT.
إنشاء أحداث للأدلة—على سبيل المثال، عند استدعاء opendir(3) و readdir(3) (لكن انظر BUGS) و closedir(3). بدون هذا العلم، تُنشأ الأحداث للملفات فقط. في سياق أحداث إدخالات الأدلة، مثل FAN_CREATE و FAN_DELETE و FAN_MOVED_FROM و FAN_MOVED_TO، يُشترط تحديد العلم FAN_ONDIR لإنشاء أحداث عند تعديل إدخالات الأدلة الفرعية (أي mkdir(2) أو rmdir(2)).
يجب إنشاء أحداث للأبناء المباشرين للأدلة الموشومة. ليس لهذا العلم تأثير عند وسم الوصلات وأنظمة الملفات. لاحظ أن الأحداث لا تُولّد لأبناء الأدلة الفرعية للأدلة الموشومة. وبشكل أكثر تحديداً، لا تُولّد أحداث تعديل إدخالات الأدلة FAN_CREATE و FAN_DELETE و FAN_MOVED_FROM و FAN_MOVED_TO لأي تعديلات تُجرى داخل الأدلة الفرعية للأدلة الموشومة. لاحظ أن الحدثين FAN_DELETE_SELF و FAN_MOVE_SELF لا يُولّدان لأبناء الأدلة الموشومة. ولمراقبة أشجار الأدلة الكاملة، من الضروري وسم الوصل أو نظام الملفات ذي الصلة.

تُعرَّف القيم المركبة التالية:

أُغلق ملف (FAN_CLOSE_WRITE|FAN_CLOSE_NOWRITE).
نُقل ملف أو دليل (FAN_MOVED_FROM|FAN_MOVED_TO).

كائن نظام الملفات المراد وسمه يُحدد بواسطة واصف الملف dirfd ومسار الملف المحدد في pathname:

•
إذا كان pathname قيمته NULL، فإن dirfd يحدد كائن نظام الملفات المراد وسمه.
•
إذا كان pathname قيمته NULL، وأخذ dirfd القيمة الخاصة AT_FDCWD، فسيُوسم دليل العمل الحالي.
•
إذا كان pathname مطلقًا، فإنه يحدد كائن نظام الملفات المراد وسمه، ويُتجاهل dirfd.
•
إذا كان pathname نسبيًا، ولم تكن قيمة dirfd هي AT_FDCWD، فإن كائن نظام الملفات المراد وسمه يُحدد عبر تفسير pathname بالنسبة إلى الدليل الذي يشير إليه dirfd.
•
إذا كان pathname نسبيًا، وكانت قيمة dirfd هي AT_FDCWD، فإن كائن نظام الملفات المراد وسمه يُحدد عبر تفسير pathname بالنسبة إلى دليل العمل الحالي. (انظر openat(2) لشرح حول سبب فائدة المعطى dirfd.)

قيمة الإرجاع

عند النجاح، تعيد fanotify_mark() القيمة 0. وعند حدوث خطأ، تُعاد -1، ويُضبط errno للإشارة إلى الخطأ.

الأخطاء

مُرر واصف ملف غير صالح في fanotify_fd.
مسار الملف pathname نسبي ولكن dirfd ليس AT_FDCWD ولا واصف ملف صالح.
كائن نظام الملفات المشار إليه بواسطة dirfd و pathname لديه علامة حُدّثت بدون الراية FAN_MARK_EVICTABLE، وحاول المستخدم تحديث العلامة باستخدام الراية FAN_MARK_EVICTABLE.
كائن نظام الملفات المشار إليه بواسطة dirfd و pathname لديه علامة حُدّثت باستخدام الراية FAN_MARK_IGNORE، وحاول المستخدم تحديث العلامة باستخدام الراية FAN_MARK_IGNORED_MASK.
كائن نظام الملفات المشار إليه بواسطة dirfd و pathname لديه علامة حُدّثت باستخدام الرايتين FAN_MARK_IGNORE و FAN_MARK_IGNORED_SURV_MODIFY، وحاول المستخدم تحديث العلامة باستخدام الراية FAN_MARK_IGNORE فقط.
مُررت قيمة غير صالحة في flags أو mask، أو لم يكن fanotify_fd واصف ملف fanotify.
فُتح واصف ملف fanotify باستخدام FAN_CLASS_NOTIF أو أن مجموعة fanotify تُعرف كائنات نظام الملفات عبر مقابض الملفات والقناع يحتوي على راية لأحداث الأذونات (FAN_OPEN_PERM أو FAN_ACCESS_PERM).
هُيئت المجموعة بدون FAN_REPORT_FID ولكن نوع حدث واحد أو أكثر محدد في mask يتطلب ذلك.
تحتوي flags على FAN_MARK_IGNORE، وإما FAN_MARK_MOUNT أو FAN_MARK_FILESYSTEM، ولكنها لا تحتوي على FAN_MARK_IGNORED_SURV_MODIFY.
تحتوي flags على FAN_MARK_IGNORE، ولكنها لا تحتوي على FAN_MARK_IGNORED_SURV_MODIFY، ويحدد dirfd و pathname دليلاً.
كائن نظام الملفات المشار إليه بواسطة dirfd و pathname غير مرتبط بنظام ملفات يدعم fsid (مثلاً fuse(4)). لم يكن tmpfs(5) يدعم fsid قبل لينكس 5.13. يمكن إرجاع هذا الخطأ فقط مع مجموعة fanotify التي تُعرف كائنات نظام الملفات عبر مقابض الملفات.
كائن نظام الملفات المشار إليه بواسطة dirfd و pathname غير موجود. يحدث هذا الخطأ أيضًا عند محاولة إزالة علامة من كائن غير موسوم.
تعذر تخصيص الذاكرة اللازمة.
تجاوز عدد العلامات لهذا المستخدم الحد المسموح به ولم تُحدد الراية FAN_UNLIMITED_MARKS عند إنشاء واصف ملف fanotify باستخدام fanotify_init(2). انظر fanotify(7) لتفاصيل حول هذا الحد.
هذه النواة لا تُنفذ fanotify_mark(). واجهة fanotify البرمجية متاحة فقط إذا ضُبطت النواة باستخدام CONFIG_FANOTIFY.
تحتوي flags على FAN_MARK_ONLYDIR، ولا يحدد dirfd و pathname دليلاً.
تحتوي mask_ على FAN_RENAME، ولا يحدد dirfd و pathname دليلاً.
تحتوي flags على FAN_MARK_IGNORE، أو هُيئت مجموعة fanotify بالراية FAN_REPORT_TARGET_FID، وتحتوي mask_ على أحداث تعديل مدخلات الدليل (مثل FAN_CREATE، FAN_DELETE)، أو رايات أحداث الدليل (مثل FAN_ONDIR، FAN_EVENT_ON_CHILD)، ولا يحدد dirfd و pathname دليلاً.
الكائن المشار إليه بواسطة pathname مرتبط بنظام ملفات لا يدعم ترميز مقابض الملفات. يمكن إرجاع هذا الخطأ فقط مع مجموعة fanotify التي تُعرف كائنات نظام الملفات عبر مقابض الملفات. يمكن استخدام استدعاء name_to_handle_at(2) مع الراية AT_HANDLE_FID (منذ لينكس 6.5) كاختبار للتحقق مما إذا كان نظام الملفات يدعم الإبلاغ عن الأحداث بمقابض الملفات.
العملية غير مسموح بها لأن المستدعِي يفتقر إلى قدرة مطلوبة.
كائن نظام الملفات المشار إليه بواسطة pathname يقع ضمن وحدة فرعية لنظام ملفات (مثلاً btrfs(5)) تستخدم fsid مختلفًا عن كتلة السوبر الجذرية الخاصة بها. يمكن إرجاع هذا الخطأ فقط مع مجموعة fanotify التي تُعرف كائنات نظام الملفات عبر مقابض الملفات.

المعايير

لينكس.

التاريخ

لينكس 2.6.37.

ملاحظات

FAN_OPEN_EXEC و FAN_OPEN_EXEC_PERM

عند استخدام إما FAN_OPEN_EXEC أو FAN_OPEN_EXEC_PERM ضمن mask_، ستُعاد أحداث من هذه الأنواع فقط عند حدوث تنفيذ مباشر لبرنامج. وبشكل أكثر تحديدًا، يعني هذا أن أحداثًا من هذه الأنواع ستُولد للملفات التي تُفتح باستخدام execve(2) أو execveat(2) أو uselib(2). لن تُرفع أحداث من هذه الأنواع في الحالة التي يُمرر فيها ملف إلى مفسر (أو يقرأه المفسر) للتفسير.

بالإضافة إلى ذلك، إذا وُضعت علامة أيضًا على الرابط الديناميكي للينكس، فيجب أن يتوقع المستخدم أيضًا تلقي حدث له عندما يُفتح كائن ELF بنجاح باستخدام execve(2) أو execveat(2).

على سبيل المثال، إذا استُدعي ملف ELF الثنائي التالي ووُضعت علامة FAN_OPEN_EXEC على /:


$ /bin/echo foo

سيتلقى التطبيق المستمع في هذه الحالة أحداث FAN_OPEN_EXEC لكل من ملف ELF الثنائي والمفسر، على التوالي:


/bin/echo
/lib64/ld-linux-x86-64.so.2

العلل

كانت العلل التالية موجودة قبل لينكس 3.16:

•
إذا احتوت flags على FAN_MARK_FLUSH، فيجب أن يحدد dirfd و pathname كائن نظام ملفات صالحًا، على الرغم من أن هذا الكائن لا يُستخدم.
•
لا يولد readdir(2) حدث FAN_ACCESS.
•
إذا استُدعي fanotify_mark() باستخدام FAN_MARK_FLUSH، فلا يُتحقق من flags بحثًا عن قيم غير صالحة.

انظر أيضًا

fanotify_init(2), fanotify(7)

ترجمة

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

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

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

2 مايو 2024 صفحات دليل لينكس 6.9.1