الاسم¶

epoll_ctl - واجهة تحكم لوصف ملف epoll

المكتبة¶

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

موجز¶

#include <sys/epoll.h>

int epoll_ctl(int epfd, int op, int fd,
              struct epoll_event *_Nullable event);

الوصف¶

تُستخدم استدعاء النظام هذا لإضافة أو تعديل أو إزالة إدخالات في قائمة الاهتمامات لمثيل epoll(7) المشار إليه بواصف الملف epfd. يطلب تنفيذ العملية op لواصف الملف الهدف fd.

القيم الصالحة للوسيطة op هي:

EPOLL_CTL_ADD

إضافة إدخال إلى قائمة الاهتمامات لواصف ملف epoll، epfd. يتضمن الإدخال واصف الملف fd، مرجعًا لوصف الملف المفتوح المقابل (انظر epoll(7) وopen(2))، والإعدادات المحددة في event.

EPOLL_CTL_MOD

تغيير الإعدادات المرتبطة بـ fd في قائمة الاهتمامات إلى الإعدادات الجديدة المحددة في event.

EPOLL_CTL_DEL

إزالة (إلغاء تسجيل) واصف الملف الهدف fd من قائمة الاهتمامات. يتم تجاهل الوسيطة event ويمكن أن تكون NULL (ولكن انظر الأخطاء أدناه).

تصف الوسيطة event الكائن المرتبط بواصف الملف fd. يتم وصف struct epoll_event في epoll_event(3type).

يحدد العضو data من بنية epoll_event البيانات التي يجب على النواة حفظها ثم إرجاعها (عبر epoll_wait(2)) عندما يصبح واصف الملف هذا جاهزًا.

العضو events من بنية epoll_event هو قناع بتات مكون من دمج صفر أو أكثر من أنواع الأحداث (التي تُرجعها epoll_wait(2)) وأعلام الإدخال التي تؤثر على سلوكها ولكنها لا تُرجع. أنواع الأحداث المتاحة هي:

EPOLLIN

الملف المرتبط متاح لعمليات read(2).

EPOLLOUT

الملف المرتبط متاح لعمليات write(2).

EPOLLRDHUP (منذ Linux 2.6.17)

أغلق النظير لمقبس الدفق الاتصال، أو أوقف كتابة نصف الاتصال. (هذا العلم مفيد بشكل خاص لكتابة كود بسيط لاكتشاف إغلاق النظير عند استخدام المراقبة المحفزة بالحافة.)

EPOLLPRI

يوجد حالة استثنائية على واصف الملف. انظر مناقشة POLLPRI في poll(2).

EPOLLERR

حدثت حالة خطأ على واصف الملف المرتبط. يتم الإبلاغ عن هذا الحدث أيضًا لنهاية الكتابة للأنبوب عندما تكون نهاية القراءة قد أغلقت.

ستقوم epoll_wait(2) دائمًا بالإبلاغ عن هذا الحدث؛ ليس من الضروري تعيينه في events عند استدعاء epoll_ctl().

EPOLLHUP

حدث إغلاق (Hang up) على واصف الملف المرتبط.

ستنتظر epoll_wait(2) دائمًا هذا الحدث؛ ليس من الضروري تعيينه في events عند استدعاء epoll_ctl().

لاحظ أنه عند القراءة من قناة مثل أنبوب أو مقبس دفق، يشير هذا الحدث فقط إلى أن النظير أغلق نهايته من القناة. ستُرجع القراءات اللاحقة من القناة 0 (نهاية الملف) فقط بعد استهلاك جميع البيانات المعلقة في القناة.

وأعلام الإدخال المتاحة هي:

EPOLLET

يطلب إعلامًا محفزًا بالحافة لواصف الملف المرتبط. السلوك المبدئي لـ epoll هو محفز بالمستوى. انظر epoll(7) لمزيد من المعلومات التفصيلية حول الإعلام المحفز بالحافة والمحفز بالمستوى.

EPOLLONESHOT (منذ Linux 2.6.2)

يطلب إعلامًا لمرة واحدة لواصف الملف المرتبط. هذا يعني أنه بعد إعلام حدث لواصف الملف بواسطة epoll_wait(2)، يتم تعطيل واصف الملف في قائمة الاهتمامات ولن يتم الإبلاغ عن أي أحداث أخرى بواسطة واجهة epoll. يجب على المستخدم استدعاء epoll_ctl() مع EPOLL_CTL_MOD لإعادة تسليح واصف الملف بقناع حدث جديد.

EPOLLWAKEUP (منذ Linux 3.5)

إذا كانت EPOLLONESHOT وEPOLLET غير مضبوطتين وكانت العملية تمتلك القدرة CAP_BLOCK_SUSPEND، فتأكد من أن النظام لا يدخل في وضع "تعليق" أو "إسبات" أثناء تعليق هذا الحدث أو معالجته. يُعتبر الحدث قيد "المعالجة" من الوقت الذي يتم إرجاعه فيه بواسطة استدعاء epoll_wait(2) حتى الاستدعاء التالي لـ epoll_wait(2) على نفس واصف ملف epoll(7)، أو إغلاق واصف الملف ذلك، أو إزالة واصف ملف الحدث باستخدام EPOLL_CTL_DEL، أو مسح EPOLLWAKEUP لواصف ملف الحدث باستخدام EPOLL_CTL_MOD. انظر أيضًا الأخطاء.

EPOLLEXCLUSIVE (منذ Linux 4.5)

يضبط وضع إيقاظ حصري لواصف ملف epoll الذي يتم إرفاقه بواصف الملف الهدف fd. عند حدوث حدث إيقاظ وإرفاق واصفات ملفات epoll متعددة بنفس الملف الهدف باستخدام EPOLLEXCLUSIVE، سيستقبل واحد أو أكثر من واصفات ملفات epoll حدثًا باستخدام epoll_wait(2). المبدئي في هذا السيناريو (عند عدم تعيين EPOLLEXCLUSIVE) هو أن تستقبل جميع واصفات ملفات epoll حدثًا. وبالتالي فإن EPOLLEXCLUSIVE مفيد لتجنب مشاكل الازدحام الجماعي في سيناريوهات معينة.

إذا كان نفس واصف الملف موجودًا في مثيلات epoll متعددة، بعضها مع العلم EPOLLEXCLUSIVE والبعض الآخر بدونه، فسيتم توفير الأحداث لجميع مثيلات epoll التي لم تحدد EPOLLEXCLUSIVE، وواحد على الأقل من مثيلات epoll التي حددت EPOLLEXCLUSIVE.

يمكن تحديد القيم التالية بالتزامن مع EPOLLEXCLUSIVE: EPOLLIN وEPOLLOUT وEPOLLWAKEUP وEPOLLET. يمكن أيضًا تحديد EPOLLHUP وEPOLLERR، ولكن هذا غير مطلوب: كالمعتاد، يتم الإبلاغ عن هذه الأحداث دائمًا في حالة حدوثها، بغض النظر عما إذا كانت محددة في events. تؤدي محاولات تحديد قيم أخرى في events إلى الخطأ EINVAL.

يمكن استخدام EPOLLEXCLUSIVE فقط في عملية EPOLL_CTL_ADD؛ تؤدي محاولات استخدامه مع EPOLL_CTL_MOD إلى خطأ. إذا تم تعيين EPOLLEXCLUSIVE باستخدام epoll_ctl()، فإن EPOLL_CTL_MOD لاحقًا على نفس الزوج epfd, fd يؤدي إلى خطأ. سيفشل أيضًا استدعاء epoll_ctl() الذي يحدد EPOLLEXCLUSIVE في events ويحدد واصف الملف الهدف fd كمثيل epoll. الخطأ في كل هذه الحالات هو EINVAL.

قيمة الإرجاع¶

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

الأخطاء¶

EBADF

epfd أو fd ليسا واصف ملف صالحًا.

EEXIST

كانت op هي EPOLL_CTL_ADD، وواصف الملف المُقدم fd مُسجل بالفعل مع مثيل epoll هذا.

EINVAL

epfd ليس واصف ملف epoll، أو fd مطابق لـ epfd، أو العملية المطلوبة op غير مدعومة من هذه الواجهة.

EINVAL

حُدد نوع حدث غير صالح مع EPOLLEXCLUSIVE في events.

EINVAL

كانت op هي EPOLL_CTL_MOD وتضمنت events EPOLLEXCLUSIVE.

EINVAL

كانت op هي EPOLL_CTL_MOD وقد طُبقت العلامة EPOLLEXCLUSIVE سابقًا على هذا الزوج epfd, fd.

EINVAL

حُدد EPOLLEXCLUSIVE في event ويشير fd إلى مثيل epoll.

ELOOP

يشير fd إلى مثيل epoll وستؤدي عملية EPOLL_CTL_ADD هذه إلى حلقة دائرية من مثيلات epoll تراقب بعضها البعض أو عمق تداخل لمثيلات epoll أكبر من 5.

ENOENT

كانت op هي EPOLL_CTL_MOD أو EPOLL_CTL_DEL، وfd غير مُسجل مع مثيل epoll هذا.

ENOMEM

كانت الذاكرة غير كافية لمعالجة عملية التحكم op المطلوبة.

ENOSPC

وُجد الحد المفروض بواسطة /proc/sys/fs/epoll/max_user_watches أثناء محاولة تسجيل (EPOLL_CTL_ADD) واصف ملف جديد على مثيل epoll. انظر epoll(7) لمزيد من التفاصيل.

EPERM

الملف الهدف fd لا يدعم epoll. يمكن أن يحدث هذا الخطأ إذا كان fd يشير، على سبيل المثال، إلى ملف عادي أو دليل.

المعايير¶

لينكس.

التاريخ¶

لينكس 2.6، glibc 2.3.2.

ملاحظات¶

واجهة epoll تدعم جميع واصفات الملفات التي تدعم poll(2).

العلل¶

قبل لينكس 2.6.9، تطلبت عملية EPOLL_CTL_DEL مؤشرًا غير فارغ في event، على الرغم من تجاهل هذه الوسيطة. منذ لينكس 2.6.9، يمكن تحديد event كـ NULL عند استخدام EPOLL_CTL_DEL. التطبيقات التي تحتاج إلى أن تكون محمولة على أنوية قبل لينكس 2.6.9 يجب أن تحدد مؤشرًا غير فارغ في event.

إذا حُدد EPOLLWAKEUP في flags، لكن المستدعي لا يمتلك القدرة CAP_BLOCK_SUSPEND، فإن العلامة EPOLLWAKEUP تُتجاهل بصمت. هذا السلوك المؤسف ضروري لأنه لم تُجرَ فحوصات صلاحية على وسيطة flags في التنفيذ الأصلي، وإضافة EPOLLWAKEUP مع فحص يتسبب في فشل الاستدعاء إذا لم يمتلك المستدعي القدرة CAP_BLOCK_SUSPEND تسبب في كسر تطبيق واحد على الأقل في مساحة المستخدم الذي صادف أنه حدد هذه البتة عشوائيًا (وبدون فائدة). لذلك يجب على التطبيق القوي التحقق مرة أخرى من امتلاكه القدرة CAP_BLOCK_SUSPEND إذا كان يحاول استخدام العلامة EPOLLWAKEUP.

انظر أيضًا¶

epoll_create(2)، epoll_wait(2)، ioctl_eventpoll(2)، poll(2)، epoll(7)

ترجمة¶

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

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

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