.\" -*- coding: UTF-8 -*- .\" Copyright 2006-2019, Michael Kerrisk .\" Copyright, the authors of the Linux man-pages project .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH poll 2 "8 فبراير 2026" "صفحات دليل لينكس 6.18" .SH الاسم poll, ppoll \- انتظار حدث ما على واصف ملف .SH المكتبة مكتبة سي المعيارية (\fIlibc\fP،\ \fI\-lc\fP) .SH موجز .nf \fB#include \fP .P \fBint poll(struct pollfd *\fP\fIfds\fP\fB, nfds_t \fP\fInfds\fP\fB, int \fP\fItimeout\fP\fB);\fP .P \fB#define _GNU_SOURCE\fP /* انظر feature_test_macros(7) */ \fB#include \fP .P \fBint ppoll(struct pollfd *\fP\fIfds\fP\fB, nfds_t \fP\fInfds\fP\fB,\fP \fB const struct timespec *_Nullable \fP\fItmo_p\fP\fB,\fP \fB const sigset_t *_Nullable \fP\fIsigmask\fP\fB);\fP .fi .SH الوصف تقوم \fBpoll\fP() بمهمة مشابهة لـ \fBselect\fP(2): فهي تنتظر حتى يصبح أحد مجموعة من واصفات الملفات جاهزًا لأداء الإدخال/الإخراج. تؤدي واجهة برمجة التطبيقات الخاصة بلينكس \fBepoll\fP(7) مهمة مشابهة، ولكنها تقدم ميزات تتجاوز تلك الموجودة في \fBpoll\fP(). .P يتم تحديد مجموعة واصفات الملفات المراد مراقبتها في الوسيط \fIfds\fP، وهو مصفوفة من الهياكل بالشكل التالي: .P .in +4n .EX struct pollfd { int fd; /* واصف ملف */ short events; /* الأحداث المطلوبة */ short revents; /* الأحداث المعادة */ }; .EE .in .P يجب على المستدعي تحديد عدد العناصر في مصفوفة \fIfds\fP في \fInfds\fP. .P يحتوي الحقل \fIfd\fP على واصف ملف لملف مفتوح. إذا كان هذا الحقل سالبًا، فسيتم تجاهل حقل \fIevents\fP المقابل ويعيد حقل \fIrevents\fP صفرًا. (يوفر هذا طريقة سهلة لتجاهل واصف ملف لاستدعاء \fBpoll\fP() واحد: ببساطة اضبط حقل \fIfd\fP على مكمله بالبت.) .P الحقل \fIevents\fP هو معامل إدخال، قناع بت يحدد الأحداث التي يهتم بها التطبيق لواصف الملف \fIfd\fP. يمكن تحديد هذا الحقل كصفر، وفي هذه الحالة تكون الأحداث الوحيدة التي يمكن إعادتها في \fIrevents\fP هي \fBPOLLHUP\fP و \fBPOLLERR\fP و \fBPOLLNVAL\fP (انظر أدناه). .P الحقل \fIrevents\fP هو معامل إخراج، يملؤه النواة بالأحداث التي حدثت فعليًا. يمكن أن تتضمن البتات المعادة في \fIrevents\fP أيًا من تلك المحددة في \fIevents\fP، أو إحدى القيم \fBPOLLERR\fP أو \fBPOLLHUP\fP أو \fBPOLLNVAL\fP. (هذه البتات الثلاث لا معنى لها في حقل \fIevents\fP، وسيتم تعيينها في حقل \fIrevents\fP كلما كان الشرط المقابل صحيحًا.) .P إذا لم يحدث أي من الأحداث المطلوبة (ولا خطأ) لأي من واصفات الملفات، فإن \fBpoll\fP() تحظر حتى يقع أحد الأحداث. .P تحدد الوسيطة \fItimeout\fP عدد الميلي ثانية التي يجب أن تحظر فيها \fBpoll\fP() في انتظار أن يصبح واصف الملف جاهزًا. ستحظر الاستدعاء حتى: .IP \[bu] 3 يصبح واصف الملف جاهزًا؛ .IP \[bu] الاستدعاء قوطع بواسطة معالج إشارة؛ أو .IP \[bu] انتهاء المهلة. .P كونه "جاهزًا" يعني أن العملية المطلوبة لن تحظر؛ وبالتالي، فإن استقصاء \fBpoll\fP() للملفات العادية وأجهزة الكتل والملفات الأخرى التي لا تحتوي على دلالات استقصاء معقولة يعود \fIدائمًا\fP فورًا كجاهز للقراءة والكتابة. .P لاحظ أن الفاصل الزمني \fItimeout\fP سيتم تقريبه لأعلى إلى دقة ساعة النظام، وتأخيرات جدولة النواة تعني أن فترة الحظر قد تتجاوز بمقدار صغير. تحديد قيمة سالبة في \fItimeout\fP يعني مهلة غير محدودة. تحديد \fItimeout\fP بقيمة صفر يتسبب في عودة \fBpoll\fP() فورًا، حتى لو لم تكن أي واصفات ملفات جاهزة. .P البتات التي يمكن تعيينها/إعادتها في \fIevents\fP و \fIrevents\fP معرفة في \fI\fP: .TP \fBPOLLIN\fP توجد بيانات للقراءة. .TP \fBPOLLPRI\fP توجد حالة استثنائية على واصف الملف. تشمل الاحتمالات: .RS .IP \[bu] 3 توجد بيانات خارج النطاق على مقبس TCP (انظر \fBtcp\fP(7)). .IP \[bu] رأى رئيس طرفي زائف في وضع الحزمة تغيير حالة على التابع (انظر \fBioctl_tty\fP(2)). .IP \[bu] تم تعديل ملف \fIcgroup.events\fP (انظر \fBcgroups\fP(7)). .RE .TP \fBPOLLOUT\fP الكتابة ممكنة الآن، على الرغم من أن كتابة أكبر من المساحة المتاحة في مقبس أو أنبوب ستظل تحظر (ما لم يتم تعيين \fBO_NONBLOCK\fP). .TP \fBPOLLRDHUP\fP (منذ لينكس 2.6.17) أغلق نظير مقبس الدفق الاتصال، أو أوقف كتابة نصف الاتصال. يجب تعريف ماكرو اختبار الميزة \fB_GNU_SOURCE\fP (قبل تضمين \fIأي\fP ملفات رأس) للحصول على هذا التعريف. .TP \fBPOLLERR\fP حالة خطأ (تُعاد فقط في \fIrevents\fP؛ تُتجاهل في \fIevents\fP). يتم تعيين هذه البتة أيضًا لواصف ملف يشير إلى نهاية الكتابة لأنبوب عندما يتم إغلاق نهاية القراءة. .TP \fBPOLLHUP\fP تعليق (يُعاد فقط في \fIrevents\fP؛ يُتجاهل في \fIevents\fP). لاحظ أنه عند القراءة من قناة مثل أنبوب أو مقبس دفق، يشير هذا الحدث فقط إلى أن النظير أغلق نهايته من القناة. ستعيد القراءات اللاحقة من القناة 0 (نهاية الملف) فقط بعد استهلاك جميع البيانات المعلقة في القناة. .TP \fBPOLLNVAL\fP طلب غير صالح: \fIfd\fP غير مفتوح (يُعاد فقط في \fIrevents\fP؛ يُتجاهل في \fIevents\fP). .P عند الترجمة مع تعريف \fB_XOPEN_SOURCE\fP، تتوفر أيضًا القيم التالية، التي لا تنقل معلومات إضافية تتجاوز البتات المذكورة أعلاه: .TP \fBPOLLRDNORM\fP مكافئ لـ \fBPOLLIN\fP. .TP \fBPOLLRDBAND\fP .\" POLLRDBAND is used in the DECnet protocol. يمكن قراءة بيانات النطاق ذي الأولوية (غير مستخدمة عمومًا على لينكس). .TP \fBPOLLWRNORM\fP مكافئ لـ \fBPOLLOUT\fP. .TP \fBPOLLWRBAND\fP يمكن كتابة بيانات ذات أولوية. .P لينكس يعرف أيضًا \fBPOLLMSG\fP، لكنه لا يستخدمه. .SS ppoll() العلاقة بين \fBpoll\fP() و\fBppoll\fP() مماثلة للعلاقة بين \fBselect\fP(2) و\fBpselect\fP(2): مثل \fBpselect\fP(2)، يسمح \fBppoll\fP() للتطبيق بالانتظار بأمان حتى يصبح واصف ملف جاهزًا أو حتى يتم التقاط إشارة. .P بخلاف الاختلاف في دقة وسيط \fItimeout\fP، فإن استدعاء \fBppoll\fP() التالي: .P .in +4n .EX ready = ppoll(&fds, nfds, tmo_p, &sigmask); .EE .in .P يكاد يكون مكافئًا لتنفيذ الاستدعاءات التالية \fIبشكل ذري\fP: .P .in +4n .EX sigset_t origmask; int timeout; \& timeout = (tmo_p == NULL) ? \-1 : (tmo_p\->tv_sec * 1000 + tmo_p\->tv_nsec / 1000000); pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); ready = poll(&fds, nfds, timeout); pthread_sigmask(SIG_SETMASK, &origmask, NULL); .EE .in .P يُوصف مقطع الكود أعلاه بأنه \fIيكاد\fP يكون مكافئًا لأنه بينما تُفسر قيمة \fItimeout\fP السالبة لـ \fBpoll\fP() على أنها مهلة لا نهائية، تؤدي القيمة السالبة المعبر عنها في \fI*tmo_p\fP إلى خطأ من \fBppoll\fP(). .P انظر وصف \fBpselect\fP(2) لشرح سبب ضرورة \fBppoll\fP(). .P إذا تم تحديد وسيط \fIsigmask\fP كـ NULL، فلا يتم إجراء أي معالجة لقناع الإشارة (وبالتالي يختلف \fBppoll\fP() عن \fBpoll\fP() فقط في دقة وسيط \fItimeout\fP). .P يحدد وسيط \fItmo_p\fP حدًا أعلى لمقدار الوقت الذي سينتظر فيه \fBppoll\fP() بشكل محظور. هذا الوسيط هو مؤشر لبنية \fBtimespec\fP(3). .P إذا تم تحديد \fItmo_p\fP كـ NULL، فيمكن لـ \fBppoll\fP() الانتظار بشكل محظور إلى أجل غير مسمى. .SH "قيمة الإرجاع" عند النجاح، تُرجع \fBpoll\fP() قيمة غير سالبة وهي عدد العناصر في \fIpollfds\fP التي تم تعيين حقول \fIrevents\fP فيها إلى قيمة غير صفرية (تشير إلى حدث أو خطأ). تشير قيمة الإرجاع صفر إلى أن استدعاء النظام انتهت مهلة قبل أن يصبح أي واصف ملف جاهزًا. .P عند الخطأ، تُعاد القيمة \-1، ويُضبط \fIerrno\fP للإشارة إلى الخطأ. .SH الأخطاء .TP \fBEFAULT\fP يشير \fIfds\fP إلى خارج مساحة العنوان القابلة للوصول للعملية. المصفوفة المعطاة كوسيط لم تكن موجودة في مساحة عنوان البرنامج المستدعي. .TP \fBEINTR\fP حدثت إشارة قبل أي حدث مطلوب؛ انظر \fBsignal\fP(7). .TP \fBEINVAL\fP قيمة \fInfds\fP تتجاوز قيمة \fBRLIMIT_NOFILE\fP. .TP \fBEINVAL\fP (\fBppoll\fP()) قيمة المهلة المعبر عنها في \fI*tmo_p\fP غير صالحة (سالبة). .TP \fBENOMEM\fP غير قادر على تخصيص ذاكرة لهياكل بيانات النواة. .SH الإصدارات .\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett على بعض أنظمة UNIX الأخرى، يمكن أن يفشل \fBpoll\fP() مع الخطأ \fBEAGAIN\fP إذا فشل النظام في تخصيص موارد داخلية للنواة، بدلاً من \fBENOMEM\fP كما يفعل لينكس. يسمح POSIX بهذا السلوك. قد ترغب البرامج المحمولة في التحقق من \fBEAGAIN\fP والتكرار، تمامًا كما هو الحال مع \fBEINTR\fP. .P تعرف بعض التطبيقات الثابت غير القياسي \fBINFTIM\fP بالقيمة \-1 لاستخدامه كـ \fItimeout\fP لـ \fBpoll\fP(). هذا الثابت غير متوفر في glibc. .SS "الاختلافات بين مكتبة C والنواة" استدعاء النظام \fBppoll\fP() في لينكس يُعدّل وسيطته \fItmo_p\fP. لكن دالة الغلاف glibc تُخفي هذا السلوك باستخدام متغير محلي لوسيطة المهلة التي تُمرّر لاستدعاء النظام. وبالتالي، دالة \fBppoll\fP() في glibc لا تُعدّل وسيطتها \fItmo_p\fP. .P استدعاء النظام الخام \fBppoll\fP() يمتلك وسيطة خامسة، \fIsize_t sigsetsize\fP، التي تُحدد الحجم بالبايت لوسيطة \fIsigmask\fP. دالة الغلاف \fBppoll\fP() في glibc تُحدد هذه الوسيطة بقيمة ثابتة (تساوي \fIsizeof(kernel_sigset_t)\fP). انظر \fBsigprocmask\fP(2) لمناقشة الفروقات بين مفهوم النواة و libc لـ sigset. .SH المعايير POSIX.1\-2024. .SH التاريخ .TP \fBpoll\fP() POSIX.1\-2001. لينكس 2.1.23. .IP على النوى القديمة التي تفتقر لاستدعاء النظام هذا، دالة الغلاف \fBpoll\fP() في glibc تُوفّر محاكاة باستخدام \fBselect\fP(2). .TP \fBppoll\fP() POSIX.1\-2024. لينكس 2.6.16، glibc 2.4. .SH ملاحظات عملية \fBpoll\fP() و \fBppoll\fP() لا تتأثر بالعلامة \fBO_NONBLOCK\fP. .P لمناقشة ما قد يحدث إذا أُغلق واصف ملف يُراقَب بواسطة \fBpoll\fP() في خيط آخر، انظر \fBselect\fP(2). .SH العلل انظر مناقشة إشعارات الجاهزية الزائفة تحت قسم BUGS في \fBselect\fP(2). .SH أمثلة البرنامج أدناه يفتح كل ملف مُسمّى في وسائط سطر الأوامر ويُراقب واصفات الملف الناتجة للجاهزية للقراءة (\fBPOLLIN\fP). البرنامج يُكرر، مستخدماً \fBpoll\fP() بشكل متكرر لمراقبة واصفات الملف، طابعاً عدد واصفات الملف الجاهزة عند العودة. لكل واصف ملف جاهز، البرنامج: .IP \[bu] 3 يعرض حقل \fIrevents\fP المُعاد بصيغة قابلة للقراءة البشرية؛ .IP \[bu] إذا كان واصف الملف قابلاً للقراءة، يقرأ بعض البيانات منه، ويعرض تلك البيانات على المخرجات القياسية؛ و .IP \[bu] إذا لم يكن واصف الملف قابلاً للقراءة، لكن حدث آخر وقع (يفترض \fBPOLLHUP\fP)، يُغلق واصف الملف. .P لنفترض أننا نشغّل البرنامج في طرفية واحدة، نطلب منه فتح FIFO: .P .in +4n .EX $\fB mkfifo myfifo\fP; $\fB ./poll_input myfifo\fP; .EE .in .P في نافذة طرفية ثانية، نفتح FIFO للكتابة، نكتب بعض البيانات إليه، ونُغلق FIFO: .P .in +4n .EX $\fB echo aaaaabbbbbccccc > myfifo\fP; .EE .in .P في الطرفية حيث نشغّل البرنامج، سنرى بعدها: .P .in +4n .EX Opened "myfifo" on fd 3 About to poll() Ready: 1 fd=3; events: POLLIN POLLHUP read 10 bytes: aaaaabbbbb About to poll() Ready: 1 fd=3; events: POLLIN POLLHUP read 6 bytes: ccccc \& About to poll() Ready: 1 fd=3; events: POLLHUP closing fd 3 All file descriptors closed. Bye. .EE .in .P في المخرجات أعلاه، نرى أن \fBpoll\fP() عاد ثلاث مرات: .IP \[bu] 3 في العودة الأولى، البتات المُعادة في حقل \fIrevents\fP كانت \fBPOLLIN\fP، مشيرة إلى أن واصف الملف قابل للقراءة، و \fBPOLLHUP\fP، مشيرة إلى أن الطرف الآخر من FIFO أُغلق. البرنامج استهلك بعدها بعضاً من المُدخلات المتاحة. .IP \[bu] العودة الثانية من \fBpoll\fP() أشارت أيضًا إلى \fBPOLLIN\fP و \fBPOLLHUP\fP؛ البرنامج استهلك بعدها آخر المُدخلات المتاحة. .IP \[bu] .\" في العودة النهائية، \fBpoll\fP() أشار فقط إلى \fBPOLLHUP\fP على FIFO، وعندها أُغلق واصف الملف وانتهى البرنامج. .SS "مصدر البرنامج" .\" SRC BEGIN (poll_input.c) \& .EX /* poll_input.c \& Licensed under GNU General Public License v2 or later. */ #include #include #include #include #include #include #include \& int main(int argc, char *argv[]) { int ready; char buf[10]; nfds_t num_open_fds, nfds; ssize_t s; struct pollfd *pfds; \& if (argc < 2) { fprintf(stderr, "Usage: %s file...\[rs]n", argv[0]); exit(EXIT_FAILURE); } \& num_open_fds = nfds = argc \- 1; pfds = calloc(nfds, sizeof(struct pollfd)); if (pfds == NULL) err(EXIT_FAILURE, "malloc"); \& /* Open each file on command line, and add it to \[aq]pfds\[aq] array. */ \& for (nfds_t j = 0; j < nfds; j++) { pfds[j].fd = open(argv[j + 1], O_RDONLY); if (pfds[j].fd == \-1) err(EXIT_FAILURE, "open"); \& printf("Opened \[rs]"%s\[rs]" on fd %d\[rs]n", argv[j + 1], pfds[j].fd); \& pfds[j].events = POLLIN; } \& /* Keep calling poll() as long as at least one file descriptor is open. */ \& while (num_open_fds > 0) { printf("About to poll()\[rs]n"); ready = poll(pfds, nfds, \-1); if (ready == \-1) err(EXIT_FAILURE, "poll"); \& printf("Ready: %d\[rs]n", ready); \& /* Deal with array returned by poll(). */ \& for (nfds_t j = 0; j < nfds; j++) { if (pfds[j].revents != 0) { printf(" fd=%d; events: %s%s%s\[rs]n", pfds[j].fd, (pfds[j].revents & POLLIN) ? "POLLIN " : "", (pfds[j].revents & POLLHUP) ? "POLLHUP " : "", (pfds[j].revents & POLLERR) ? "POLLERR " : ""); \& if (pfds[j].revents & POLLIN) { s = read(pfds[j].fd, buf, sizeof(buf)); if (s == \-1) err(EXIT_FAILURE, "read"); printf(" read %zd bytes: %.*s\[rs]n", s, (int) s, buf); } else { /* POLLERR | POLLHUP */ printf(" closing fd %d\[rs]n", pfds[j].fd); if (close(pfds[j].fd) == \-1) err(EXIT_FAILURE, "close"); num_open_fds\-\-; } } } } \& printf("All file descriptors closed. Bye.\[rs]n"); exit(EXIT_SUCCESS); } .EE .\" SRC END .SH "انظر أيضًا" \fBrestart_syscall\fP(2), \fBselect\fP(2), \fBselect_tut\fP(2), \fBtimespec\fP(3), \fBepoll\fP(7), \fBtime\fP(7) .PP .SH ترجمة تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي . .PP هذه الترجمة هي وثيقة مجانية؛ راجع .UR https://www.gnu.org/licenses/gpl-3.0.html رخصة جنو العامة الإصدار 3 .UE أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات. .PP إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: .MT kde-l10n-ar@kde.org .ME .