mq_open(3)

الاسم
mq_open - فتح طابور رسائل

المكتبة
مكتبة الوقت الحقيقي (librt، -lrt)

موجز
#include <fcntl.h>           /* من أجل ثوابت O_* */
#include <sys/stat.h>        /* من أجل ثوابت الوضع */
#include <mqueue.h>

mqd_t mq_open(const char *name, int oflag);
mqd_t mq_open(const char *name, int oflag, mode_t mode,
              struct mq_attr *attr);

الوصف
تنشئ mq_open() طابور رسائل POSIX جديد أو تفتح طابورًا موجودًا. يُحدد الطابور بواسطة name. للتفاصيل حول بناء name، انظر mq_overview(7).

يحدد المعامل oflag الأعلام التي تتحكم في عملية الاستدعاء. (يمكن الحصول على تعريفات قيم الأعلام بتضمين <fcntl.h>.) يجب تحديد واحد بالضبط مما يلي في oflag:

O_RDONLY
    فتح الطابور لاستقبال الرسائل فقط.

O_WRONLY
    فتح الطابور لإرسال الرسائل فقط.

O_RDWR
    فتح الطابور لإرسال واستقبال الرسائل معًا.

يمكن إضافة صفر أو أكثر من الأعلام التالية بعملية OR في oflag:

O_CLOEXEC (منذ لينكس 2.6.26)
    يضبط علم الإغلاق عند التنفيذ لوصف طابور الرسائل. انظر open(2) لمناقشة فائدة هذا العلم.

O_CREAT
    ينشئ طابور الرسائل إذا لم يكن موجودًا. يُضبط المالك (معرف المستخدم) لطابور الرسائل على معرف المستخدم الفعّال للعملية المستدعية. تُضبط ملكية المجموعة (معرف المجموعة) على معرف المجموعة الفعّال للعملية المستدعية.

O_EXCL
    إذا حُدد O_CREAT في oflag، وكان طابور بالاسم name المحدد موجودًا بالفعل، فسيفشل الاستدعاء مع الخطأ EEXIST.

O_NONBLOCK
    يفتح الطابور في وضع عدم الحظر. في الظروف التي كانت فيها mq_receive(3) و mq_send(3) ستحظر عادةً، تفشل هذه الدوال بدلاً من ذلك مع الخطأ EAGAIN.

إذا حُدد O_CREAT في oflag، فيجب توفير معاملين إضافيين. يحدد المعامل mode الأذونات التي ستوضع على الطابور الجديد، كما في open(2). (يمكن الحصول على التعريفات الرمزية لبتات الأذونات بتضمين <sys/stat.h>.) تُقنّع إعدادات الأذونات بقناع umask للعملية.

تحدد حقول struct mq_attr المشار إليها بواسطة attr العدد الأقصى للرسائل والحجم الأقصى للرسائل الذي سيسمح به الطابور. يُعرف هذا الهيكل كما يلي:

    struct mq_attr {
        long mq_flags;       /* الأعلام (تُتجاهل لـ mq_open()) */
        long mq_maxmsg;      /* العدد الأقصى للرسائل في الطابور */
        long mq_msgsize;     /* الحجم الأقصى للرسالة (بايت) */
        long mq_curmsgs;     /* عدد الرسائل الموجودة حاليًا في الطابور
                                (يُتجاهل لـ mq_open()) */
    };

تُستخدم حقول mq_maxmsg و mq_msgsize فقط عند استدعاء mq_open()؛ تُتجاهل القيم في الحقول المتبقية.

إذا كان attr NULL، فسيُنشأ الطابور بسمات مبدئية محددة بالتنفيذ. منذ لينكس 3.5، يمكن استخدام ملفين /proc للتحكم في هذه المبدئيات؛ انظر mq_overview(7) للتفاصيل.

قيمة الإرجاع
عند النجاح، تُرجع mq_open() واصف طابور رسائل لاستخدامه من قبل دوال طابور الرسائل الأخرى. عند الخطأ، تُرجع mq_open() (mqd_t) -1، مع ضبط errno للإشارة إلى الخطأ.

الأخطاء

EACCES
    قائمة الانتظار موجودة، لكن المتصل لا يملك صلاحية فتحها بالوضع المحدد.

EACCES
    احتوى name على أكثر من شرطة مائلة واحدة.

EEXIST
    حُدد كل من O_CREAT و O_EXCL في oflag، لكن قائمة انتظار بهذا name موجودة مسبقًا.

EINVAL
    لا يتبع name التنسيق المذكور في mq_overview(7).

EINVAL
    حُدد O_CREAT في oflag، وكان attr غير فارغ، لكن attr->mq_maxmsg أو attr->mq_msqsize كان غير صالح. يجب أن يكون كلا هذين الحقلين أكبر من الصفر. في عملية غير مميزة (لا تملك القدرة CAP_SYS_RESOURCE)، يجب أن يكون attr->mq_maxmsg أقل من أو يساوي حد msg_max، ويجب أن يكون attr->mq_msgsize أقل من أو يساوي حد msgsize_max. بالإضافة إلى ذلك، حتى في عملية مميزة، لا يمكن أن يتجاوز attr->mq_maxmsg حد HARD_MAX. (انظر mq_overview(7) لتفاصيل هذه الحدود.)

EMFILE
    وُصل إلى الحد الخاص بكل عملية لعدد واصفات الملفات وقوائم انتظار الرسائل المفتوحة (انظر وصف RLIMIT_NOFILE في getrlimit(2)).

ENAMETOOLONG
    الاسم name كان طويلاً جداً.

ENFILE
    وُصل إلى الحد على مستوى النظام للعدد الإجمالي للملفات وقوائم انتظار الرسائل المفتوحة.

ENOENT
    لم يحُدد العلم O_CREAT في oflag، ولا توجد قائمة انتظار بهذا name.

ENOENT
    كان name مجرد "/" دون أحرف أخرى بعده.

ENOMEM
    ذاكرة غير كافية.

ENOSPC
    مساحة غير كافية لإنشاء قائمة انتظار رسائل جديدة. حدث هذا غالبًا بسبب الوصول إلى حد queues_max؛ انظر mq_overview(7).

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
mq_open() | سلامة الخيوط | MT-Safe

الإصدارات

  الاختلافات بين مكتبة C والنواة
دالة المكتبة mq_open() مطبقة فوق استدعاء نظام بنفس الاسم. تقوم دالة المكتبة بالتحقق من أن name يبدأ بشرطة مائلة (/) وتعطي الخطأ EINVAL إذا لم يبدأ بها. يتوقع استدعاء النظام في النواة ألا يحتوي name على شرطة مائلة سابقة، لذا تمرر دالة مكتبة C name بدون الشرطة المائلة السابقة (أي name+1) إلى استدعاء النظام.

المعايير
POSIX.1-2008.

التاريخ
POSIX.1-2001.

العلل
قبل لينكس 2.6.14، لم يكن umask العملية مطبقًا على الأذونات المحددة في mode.

انظر أيضًا
mq_close(3), mq_getattr(3), mq_notify(3), mq_receive(3), mq_send(3), mq_unlink(3), mq_overview(7)

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

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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