Scroll to navigation

fanotify_init(2) System Calls Manual fanotify_init(2)

الاسم

fanotify_init - إنشاء وتهيئة مجموعة fanotify

المكتبة

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

موجز

#include <fcntl.h>            /* تعريف ثوابت O_* */
#include <sys/fanotify.h>
int fanotify_init(unsigned int flags, unsigned int event_f_flags);

الوصف

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

fanotify_init() يهيئ مجموعة fanotify جديدة ويعيد واصف ملف لطابور الأحداث المرتبط بالمجموعة.

يُستخدم واصف الملف في استدعاءات fanotify_mark(2) لتحديد الملفات، أو الدلائل، أو نقاط الوصل، أو أنظمة الملفات التي ستُنشأ لها أحداث fanotify. تُستقبل هذه الأحداث بالقراءة من واصف الملف. بعض الأحداث إعلامية فقط، تشير إلى أن ملفاً وُصل إليه. يمكن استخدام أحداث أخرى لتحديد ما إذا كان يُسمح لتطبيق آخر بالوصول إلى ملف أو دليل. يُمنح الإذن بالوصول إلى كائنات نظام الملفات بالكتابة إلى واصف الملف.

قد تستخدم برامج متعددة واجهة fanotify في الوقت ذاته لمراقبة الملفات ذاتها.

عدد مجموعات fanotify لكل مستخدم محدود. انظر fanotify(7) للتفاصيل حول هذا الحد.

تحتوي وسيطة flags على حقل متعدد البتات يُعرّف فئة الإشعار للتطبيق المستمع وحقولاً أحادية البت إضافية تحدد سلوك واصف الملف.

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

يمكن تحديد فئة واحدة فقط من فئات الإشعار التالية في flags:

تسمح هذه القيمة باستقبال أحداث تُعلم بأن ملفاً وُصل إليه وأحداث لقرارات الإذن فيما إذا كان يمكن الوصول إلى الملف. وهي مخصصة لمستمعي الأحداث الذين قد يحتاجون إلى كتابة بيانات إلى الملفات قبل أن يمكن الوصول إلى بياناتها النهائية. قد تُستخدم فئة الإشعار هذه بواسطة مديري التخزين الهرمي، على سبيل المثال. يتطلب استخدام هذه العلامة صلاحية CAP_SYS_ADMIN.
تسمح هذه القيمة باستقبال أحداث تُعلم بأن ملفاً وُصل إليه وأحداث لقرارات الإذن فيما إذا كان يمكن الوصول إلى الملف. وهي مخصصة لمستمعي الأحداث الذين يحتاجون إلى الوصول إلى الملفات عندما تحتوي بالفعل على محتواها النهائي. قد تُستخدم فئة الإشعار هذه بواسطة برامج كشف البرامج الضارة، على سبيل المثال. يتطلب استخدام هذه العلامة صلاحية CAP_SYS_ADMIN.
هذه هي القيمة المبدئية. ولا حاجة لتحديدها. تسمح هذه القيمة فقط باستقبال أحداث تُعلم بأن ملفاً وُصل إليه. وقرارات الإذن قبل الوصول إلى الملف غير ممكنة.

سيستقبل المستمعون ذوو فئات الإشعار المختلفة الأحداث بالترتيب FAN_CLASS_PRE_CONTENT، ثم FAN_CLASS_CONTENT، ثم FAN_CLASS_NOTIF. ترتيب الإشعار للمستمعين في فئة الإشعار ذاتها غير محدد.

يمكن تعيين البتات التالية إضافياً في flags:

تُعيّن علامة الإغلاق عند التنفيذ (FD_CLOEXEC) على واصف الملف الجديد. انظر وصف علامة O_CLOEXEC في open(2).
تُفعّل علامة عدم الحظر (O_NONBLOCK) لواصف الملف. لن تمنع القراءة من واصف الملف. وبدلاً من ذلك، إذا لم تكن هناك بيانات متاحة، يفشل read(2) مع الخطأ EAGAIN.
يُزال الحد على عدد الأحداث في طابور الأحداث. انظر fanotify(7) للتفاصيل حول هذا الحد. يتطلب استخدام هذه العلامة صلاحية CAP_SYS_ADMIN.
يُزال الحد على عدد علامات fanotify لكل مستخدم. انظر fanotify(7) للتفاصيل حول هذا الحد. يتطلب استخدام هذه العلامة صلاحية CAP_SYS_ADMIN.
يُبلَّغ عن معرف الخيط (TID) بدلاً من معرف العملية (PID) في حقل pid من struct fanotify_event_metadata المقدم إلى read(2) (انظر fanotify(7)). يتطلب استخدام هذه العلامة صلاحية CAP_SYS_ADMIN.
يُفعّل توليد سجلات تدقيق حول الوساطة في الوصول التي تُجرى بواسطة أحداث الإذن. يجب وسم استجابة حدث الإذن بالعلامة FAN_AUDIT لتوليد سجل تدقيق. يتطلب استخدام هذه العلامة صلاحية CAP_AUDIT_WRITE.
تسمح هذه القيمة باستقبال الأحداث التي تحتوي على معلومات إضافية حول كائن نظام الملفات الأساسي المرتبط بحدث. يُغلف سجل إضافي من النوع FAN_EVENT_INFO_TYPE_FID المعلومات حول الكائن ويُدرج بجانب بنية بيانات الحدث العامة. يُستبدل واصف الملف المستخدم لتمثيل الكائن المرتبط بحدث بمقبض ملف. ويُقصد به التطبيقات التي قد تجد استخدام مقبض ملف لتحديد كائن أكثر ملاءمة من واصف ملف. بالإضافة إلى ذلك، يمكن استخدامه للتطبيقات التي تراقب دليلاً أو نظام ملفات وتهتم بأحداث تعديل إدخال الدليل FAN_CREATE و FAN_DELETE و FAN_MOVE و FAN_RENAME، أو بأحداث مثل FAN_ATTRIB و FAN_DELETE_SELF و FAN_MOVE_SELF. تتطلب جميع الأحداث المذكورة أعلاه مجموعة fanotify تحدد كائنات نظام الملفات بواسطة مقابض الملفات. لاحظ أنه بدون العلامة FAN_REPORT_TARGET_FID، بالنسبة لأحداث تعديل إدخال الدليل، يوجد سجل معلومات يحدد الدليل المعدل وليس الكائن الفرعي المنشأ/المحذوف/المنقول. لا يُسمح باستخدام FAN_CLASS_CONTENT أو FAN_CLASS_PRE_CONTENT مع هذه العلامة وسيؤدي ذلك إلى الخطأ EINVAL. انظر fanotify(7) للحصول على تفاصيل إضافية.
ستحتوي أحداث مجموعات fanotify المُهيأة بهذه العلامة (انظر الاستثناءات أدناه) على معلومات إضافية حول كائن دليل مرتبط بحدث. يُغلف سجل إضافي من النوع FAN_EVENT_INFO_TYPE_DFID المعلومات حول كائن الدليل ويُدرج بجانب بنية بيانات الحدث العامة. بالنسبة للأحداث التي تحدث على كائن غير دليل، تتضمن البنية الإضافية مقبض ملف يحدد كائن نظام ملفات الدليل الأصل. لاحظ أنه لا يوجد ضمان بأنه سيُعثر على كائن نظام ملفات الدليل في الموقع الموصوف بمعلومات مقبض الملف في وقت استقبال الحدث. عند دمجها مع العلامة FAN_REPORT_FID، قد يُبلَّغ عن سجلين مع الأحداث التي تحدث على كائن غير دليل، أحدهما لتحديد الكائن غير الدليل نفسه والآخر لتحديد كائن الدليل الأصل. لاحظ أنه في بعض الحالات، لا يحتوي كائن نظام الملفات على أصل، على سبيل المثال، عند حدوث حدث على ملف غير مرتبط ولكنه مفتوح. في تلك الحالة، مع العلامة FAN_REPORT_FID، سيُبلَّغ عن الحدث بسجل واحد فقط لتحديد الكائن غير الدليل نفسه، لأنه لا يوجد دليل مرتبط بالحدث. وبدون العلامة FAN_REPORT_FID، لن يُبلَّغ عن أي حدث. انظر fanotify(7) للحصول على تفاصيل إضافية.
ستحتوي أحداث مجموعات fanotify المُهيأة بهذه العلامة على معلومات إضافية حول اسم إدخال الدليل المرتبط بحدث. يجب توفير هذه العلامة بالتزامن مع العلامة FAN_REPORT_DIR_FID. سيؤدي توفير قيمة هذه العلامة بدون FAN_REPORT_DIR_FID إلى الخطأ EINVAL. يمكن دمج هذه العلامة مع العلامة FAN_REPORT_FID. يُدرج سجل إضافي من النوع FAN_EVENT_INFO_TYPE_DFID_NAME، والذي يُغلف المعلومات حول إدخال الدليل، بجانب بنية بيانات الحدث العامة ويحل محل سجل المعلومات الإضافية من النوع FAN_EVENT_INFO_TYPE_DFID. يتضمن السجل الإضافي مقبض ملف يحدد كائن نظام ملفات دليل متبوعاً باسم يحدد إدخالاً في ذلك الدليل. بالنسبة لأحداث تعديل إدخال الدليل FAN_CREATE و FAN_DELETE و FAN_MOVE، يكون الاسم المُبلَّغ عنه هو اسم إدخال الدليل المنشأ/المحذوف/المنقول. قد يحتوي الحدث FAN_RENAME على سجلين للمعلومات، أحدهما من النوع FAN_EVENT_INFO_TYPE_OLD_DFID_NAME يحدد إدخال الدليل القديم، والآخر من النوع FAN_EVENT_INFO_TYPE_NEW_DFID_NAME يحدد إدخال الدليل الجديد. بالنسبة للأحداث الأخرى التي تحدث على كائن دليل، يكون مقبض الملف المُبلَّغ عنه هو مقبض كائن الدليل ذاته والاسم المُبلَّغ عنه هو '.'. بالنسبة للأحداث الأخرى التي تحدث على كائن غير دليل، يكون مقبض الملف المُبلَّغ عنه هو مقبض كائن الدليل الأصل والاسم المُبلَّغ عنه هو اسم إدخال الدليل حيث كان الكائن موجوداً في وقت الحدث. الأساس المنطقي وراء هذا المنطق هو أنه يمكن تمرير مقبض ملف الدليل المُبلَّغ عنه إلى open_by_handle_at(2) للحصول على واصف ملف دليل مفتوح، ويمكن استخدام واصف الملف هذا مع الاسم المُبلَّغ عنه لاستدعاء fstatat(2). تنطبق القاعدة ذاتها التي تنطبق على نوع السجل FAN_EVENT_INFO_TYPE_DFID أيضًا على نوع السجل FAN_EVENT_INFO_TYPE_DFID_NAME: إذا لم يكن لكائن غير دليل أصل، فلن يُبلَّغ عن الحدث أو سيُبلَّغ عنه بدون معلومات إدخال الدليل. لاحظ أنه لا يوجد ضمان بأنه سيُعثر على كائن نظام الملفات في الموقع الموصوف بمعلومات إدخال الدليل في وقت استقبال الحدث. انظر fanotify(7) للحصول على تفاصيل إضافية.
هذا مرادف لـ (FAN_REPORT_DIR_FID|FAN_REPORT_NAME).
ستحتوي أحداث مجموعات fanotify المُهيأة بهذه العلامة على معلومات إضافية حول الكائن الفرعي المرتبط بأحداث تعديل إدخال الدليل. يجب توفير هذه العلامة بالتزامن مع العلامات FAN_REPORT_FID و FAN_REPORT_DIR_FID و FAN_REPORT_NAME، وإلا سيُرجع الخطأ EINVAL. بالنسبة لأحداث تعديل إدخال الدليل FAN_CREATE و FAN_DELETE و FAN_MOVE و FAN_RENAME، يُبلَّغ عن سجل إضافي من النوع FAN_EVENT_INFO_TYPE_FID بالإضافة إلى سجلات المعلومات من النوع FAN_EVENT_INFO_TYPE_DFID و FAN_EVENT_INFO_TYPE_DFID_NAME و FAN_EVENT_INFO_TYPE_OLD_DFID_NAME و FAN_EVENT_INFO_TYPE_NEW_DFID_NAME. يتضمن السجل الإضافي مقبض ملف يحدد كائن نظام الملفات الفرعي الذي يشير إليه إدخال الدليل.
هذا مرادف لـ (FAN_REPORT_DFID_NAME|FAN_REPORT_FID|FAN_REPORT_TARGET_FID).
تسمح هذه القيمة باستقبال الأحداث التي تحتوي على معلومات إضافية حول نقطة الوصل الأساسية المرتبطة بحدث. يُغلف سجل إضافي من النوع FAN_EVENT_INFO_TYPE_MNT المعلومات حول نقطة الوصل ويُدرج بجانب بنية بيانات الحدث العامة. لا يُسمح باستخدام FAN_CLASS_CONTENT أو FAN_CLASS_PRE_CONTENT أو أي من علامات FAN_REPORT_DFID_NAME_TARGET مع هذه العلامة وسيؤدي ذلك إلى الخطأ EINVAL. انظر fanotify(7) للحصول على تفاصيل إضافية.
ستحتوي الأحداث لمجموعات fanotify المُهيأة بهذه العلامة على سجل معلومات إضافي بجانب بنية fanotify_event_metadata العامة. سيكون سجل المعلومات هذا من النوع FAN_EVENT_INFO_TYPE_PIDFD وسيشمل pidfd للعملية المسؤولة عن توليد الحدث. لا يختلف pidfd المُرجع في كائن سجل المعلومات هذا عن pidfd المُرجع عند استدعاء pidfd_open(2). يُستخدم سجل المعلومات هذا في التطبيقات التي تهتم بتحديد ما إذا كانت العملية المسؤولة عن توليد الحدث قد أُعيد تدويرها أو أُنهيت بشكل موثوق. استخدام العلامة FAN_REPORT_TID بجانب FAN_REPORT_PIDFD غير مدعوم حالياً ومحاولة القيام بذلك ستؤدي إلى إرجاع الخطأ EINVAL. تفرض واجهة pidfd API هذا القيد حالياً لأنها لا تدعم إلا إنشاء pidfds لمتصدري مجموعات الخيوط. قد يُدعم إنشاء pidfds لغير متصدري مجموعات الخيوط في مرحلة ما في المستقبل، لذا قد يُرفع هذا القيد لاحقًا. لمزيد من التفاصيل حول سجلات المعلومات، راجع fanotify(7).
قد تحتوي الأحداث لمجموعات fanotify المُهيأة بهذه العلامة على رمز خطأ يوضح سبب الفشل في فتح واصف ملف. يحتوي عضو .fd في بنية fanotify_event_metadata عادةً على واصف ملف مفتوح مرتبط بكائن الحدث، أو FAN_NOFD في حال تعذر فتح واصف الملف. بالنسبة لمجموعة مُهيأة بهذه العلامة، وبدلاً من FAN_NOFD، سيحتوي عضو .fd في بنية fanotify_event_metadata على قيمة خطأ سالبة. وعندما تُهيأ المجموعة أيضًا بالعلامة FAN_REPORT_PIDFD، وفي حال تعذر فتح واصف ملف العملية، سيحتوي عضو .pidfd في بنية fanotify_event_info_pidfd أيضًا على قيمة خطأ سالبة. لمزيد من التفاصيل، انظر fanotify(7).

تحدد وسيطة event_f_flags علامات حالة الملف التي ستُضبط على أوصاف الملفات المفتوحة التي تُنشأ لأحداث fanotify. لتفاصيل هذه العلامات، انظر وصف قيم flags في open(2). تتضمن event_f_flags حقلاً متعدد البتات لوضع الوصول، ويمكن لهذا الحقل أن يأخذ القيم التالية:

تسمح هذه القيمة بالوصول للقراءة فقط.
تسمح هذه القيمة بالوصول للكتابة فقط.
تسمح هذه القيمة بالوصول للقراءة والكتابة.

يمكن تعيين بتات إضافية في event_f_flags، وأكثر القيم فائدة هي:

تُفعّل دعم الملفات التي تتجاوز 2 غيغابايت. سيؤدي الفشل في تعيين هذه العلامة إلى الخطأ EOVERFLOW عند محاولة فتح ملف كبير يراقبه مجموعة fanotify على نظام 32 بت.
تُفعّل علامة الإغلاق عند التنفيذ لواصف الملف. انظر وصف علامة O_CLOEXEC في open(2) للأسباب التي قد تجعل هذا مفيداً.

يُسمح أيضًا بما يلي: O_APPEND، و O_DSYNC، و O_NOATIME، و O_NONBLOCK، و O_SYNC. يؤدي تحديد أي علامة أخرى في event_f_flags إلى الخطأ EINVAL (ولكن انظر قسم العِلل).

قيمة الإرجاع

عند النجاح، يعيد fanotify_init() واصف ملف جديد. وعند الخطأ، يُعاد -1، ويُضبط errno للإشارة إلى الخطأ.

الأخطاء

مُررت قيمة غير صالحة في flags أو event_f_flags. وتحدد FAN_ALL_INIT_FLAGS (المهجورة منذ لينكس 4.20) جميع البتات المسموح بها لـ flags.
عدد مجموعات fanotify لهذا المستخدم يتجاوز الحد. انظر fanotify(7) للتفاصيل حول هذا الحد.
وُصل إلى الحد الأقصى لواصفات الملفات المفتوحة لكل عملية.
فشل تخصيص الذاكرة لمجموعة الإشعارات.
هذه النواة لا تنفذ fanotify_init(). واجهة برمجة تطبيقات fanotify متاحة فقط إذا ضُبطت النواة باستخدام CONFIG_FANOTIFY.
العملية غير مسموح بها لأن المستدعِي يفتقر إلى قدرة مطلوبة.

الإصدارات

قبل لينكس 5.13 (و 5.10.220)، كان استدعاء fanotify_init() يتطلب صلاحية CAP_SYS_ADMIN. ومنذ لينكس 5.13 (و 5.10.220)، يمكن للمستخدمين استدعاء fanotify_init() بدون صلاحية CAP_SYS_ADMIN لإنشاء وتهيئة مجموعة fanotify بوظائف محدودة.

القيود المفروضة على مستمع الأحداث الذي أنشأه مستخدم بدون
صلاحية CAP_SYS_ADMIN هي كما يلي:
•
لا يمكن للمستخدم طلب طابور أحداث غير محدود باستخدام FAN_UNLIMITED_QUEUE.
•
لا يمكن للمستخدم طلب عدد غير محدود من العلامات باستخدام FAN_UNLIMITED_MARKS.
•
لا يمكن للمستخدم طلب استخدام أي من فئات الإشعار FAN_CLASS_CONTENT أو FAN_CLASS_PRE_CONTENT. وهذا يعني أن المستخدم لا يمكنه طلب أحداث الإذن.
•
يُطلب من المستخدم إنشاء مجموعة تحدد كائنات نظام الملفات بواسطة مقابض الملفات، على سبيل المثال، بتوفير العلامة FAN_REPORT_FID.
•
يقتصر المستخدم على وسم inodes فقط. والقدرة على وسم نقطة وصل أو نظام ملفات عبر fanotify_mark() باستخدام FAN_MARK_MOUNT أو FAN_MARK_FILESYSTEM غير مسموح بها.
•
كائن الحدث في طابور الأحداث محدود من حيث المعلومات المتاحة للمستخدم غير المميز. ولن يتلقى المستخدم أيضًا معرف العملية pid الذي أنشأ الحدث، إلا إذا كانت العملية المستمعة ذاتها هي من أنشأت الحدث.

المعايير

لينكس.

التاريخ

لينكس 2.6.37.

العلل

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

•
يُتجاهل O_CLOEXEC عند تمريره في event_f_flags.

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

•
وسيطة event_f_flags لا تُفحص بحثاً عن علامات غير صالحة. ويمكن تعيين العلامات المخصصة للاستخدام الداخلي فقط، مثل FMODE_EXEC، ونتيجة لذلك ستُضبط لواصفات الملفات المُرجعة عند القراءة من واصف ملف fanotify.

انظر أيضًا

fanotify_mark(2), fanotify(7)

ترجمة

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

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

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

17 مايو 2025 صفحات دليل لينكس 6.18