msgctl(2)

الاسم
msgctl - عمليات التحكم في رسائل System V

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

موجز
#include <sys/msg.h>

int msgctl(int msqid, int op, struct msqid_ds *buf);

الوصف
تنفذ msgctl() عملية التحكم المحددة بواسطة op على قائمة انتظار رسائل System V بالمعرف msqid.

يُعرّف هيكل البيانات msqid_ds في <sys/msg.h> كما يلي:

    struct msqid_ds {
        struct ipc_perm msg_perm;   /* Ownership and permissions */
        time_t          msg_stime;  /* Time of last msgsnd(2) */
        time_t          msg_rtime;  /* Time of last msgrcv(2) */
        time_t          msg_ctime;  /* Time of creation or last
                                       modification by msgctl() */
        unsigned long   msg_cbytes; /* # of bytes in queue */
        msgqnum_t       msg_qnum;   /* # number of messages in queue */
        msglen_t        msg_qbytes; /* Maximum # of bytes in queue */
        pid_t           msg_lspid;  /* PID of last msgsnd(2) */
        pid_t           msg_lrpid;  /* PID of last msgrcv(2) */
    };

حقول هيكل msqid_ds هي كما يلي:

msg_perm
    هذا هيكل ipc_perm (انظر أدناه) يحدد أذونات الوصول إلى قائمة انتظار الرسائل.

msg_stime
    وقت آخر استدعاء نظام msgsnd(2).

msg_rtime
    وقت آخر استدعاء نظام msgrcv(2).

msg_ctime
    وقت إنشاء القائمة أو وقت آخر عملية IPC_SET لـ msgctl().

msg_cbytes
    عدد البايتات في جميع الرسائل الموجودة حالياً في قائمة انتظار الرسائل. هذا امتداد لينكس غير قياسي غير محدد في POSIX.

msg_qnum
    عدد الرسائل الموجودة حالياً في قائمة انتظار الرسائل.

msg_qbytes
    الحد الأقصى لعدد بايتات نص الرسالة المسموح بها في قائمة انتظار الرسائل.

msg_lspid
    معرف العملية التي نفذت آخر استدعاء نظام msgsnd(2).

msg_lrpid
    معرف العملية التي نفذت آخر استدعاء نظام msgrcv(2).

بنية ipc_perm مُعرفة كالتالي (الحقول المميزة قابلة للضبط باستخدام IPC_SET):

    struct ipc_perm {
        key_t          __key;       /* Key supplied to msgget(2) */
        uid_t          uid;         /* Effective UID of owner */
        gid_t          gid;         /* Effective GID of owner */
        uid_t          cuid;        /* Effective UID of creator */
        gid_t          cgid;        /* Effective GID of creator */
        unsigned short mode;        /* Permissions */
        unsigned short __seq;       /* Sequence number */
    };

تحدد أقل 9 بتات أهمية من حقل mode لهيكل ipc_perm أذونات الوصول إلى قائمة انتظار الرسائل. بتات الأذونات هي كما يلي:
0400 | مقروء من المستخدم
0200 | الكتابة بواسطة المستخدم
0040 | مقروء من المجموعة
0020 | الكتابة بواسطة المجموعة
0004 | مقروء من الآخرين
0002 | الكتابة بواسطة الآخرين

البتات 0100 و 0010 و 0001 (بتات التنفيذ) غير مستخدمة من قبل النظام.

القيم الصالحة لـ op هي:

IPC_STAT
    ينسخ المعلومات من هيكل بيانات النواة المرتبط بـ msqid إلى هيكل msqid_ds المشار إليه بواسطة buf. يجب أن يمتلك المتصل إذن قراءة على قائمة انتظار الرسائل.

IPC_SET
    يكتب قيم بعض أعضاء هيكل msqid_ds المشار إليه بواسطة buf إلى هيكل بيانات النواة المرتبط بقائمة انتظار الرسائل هذه، مع تحديث عضوه msg_ctime أيضًا.

    يتم تحديث الأعضاء التالية من الهيكل: msg_qbytes و msg_perm.uid و msg_perm.gid و (أقل 9 بتات أهمية من) msg_perm.mode.

    يجب أن يتطابق UID الفعال للعملية المستدعية مع المالك (msg_perm.uid) أو المنشئ (msg_perm.cuid) لقائمة الرسائل، أو يجب أن تكون العملية المستدعية مميزة. الامتياز المناسب (لينكس: القدرة CAP_SYS_RESOURCE) مطلوب لرفع قيمة msg_qbytes فوق المعامل النظامي MSGMNB.

IPC_RMID
    إزالة قائمة الرسائل فوراً، مع إيقاظ جميع عمليات القراءة والكتابة المنتظرة (مع إرجاع خطأ وتعيين errno إلى EIDRM). يجب أن تمتلك العملية المستدعية الامتيازات المناسبة أو أن يكون معرف المستخدم الفعال الخاص بها إما معرف منشئ أو مالك قائمة الرسائل. يتم تجاهل الوسيطة الثالثة لـ msgctl() في هذه الحالة.

IPC_INFO (خاص بلينكس)
    إرجاع معلومات حول حدود ومعاملات قائمة الرسائل على مستوى النظام في البنية المشار إليها بواسطة buf. هذه البنية من النوع msginfo (وبالتالي، يلزم تحويل النوع)، معرفة في <sys/msg.h> إذا تم تعريف ماكرو اختبار الميزة _GNU_SOURCE:

        struct msginfo {
            int msgpool; /* Size in kibibytes of buffer pool
                            used to hold message data;
                            unused within kernel */
            int msgmap;  /* Maximum number of entries in message
                            map; unused within kernel */
            int msgmax;  /* Maximum number of bytes that can be
                            written in a single message */
            int msgmnb;  /* Maximum number of bytes that can be
                            written to queue; used to initialize
                            msg_qbytes during queue creation
                            (msgget(2)) */
            int msgmni;  /* Maximum number of message queues */
            int msgssz;  /* Message segment size;
                            unused within kernel */
            int msgtql;  /* Maximum number of messages on all queues
                            in system; unused within kernel */
            unsigned short msgseg;
                         /* Maximum number of segments;
                            unused within kernel */
        };

    يمكن تغيير إعدادات msgmni و msgmax و msgmnb عبر ملفات /proc بنفس الاسم؛ انظر proc(5) للتفاصيل.

MSG_INFO (خاص بلينكس)
    إرجاع بنية msginfo تحتوي على نفس المعلومات كما في IPC_INFO، باستثناء أن الحقول التالية تُرجع مع معلومات حول موارد النظام المستهلكة بواسطة قوائم الرسائل: حقل msgpool يُرجع عدد قوائم الرسائل الموجودة حالياً على النظام؛ حقل msgmap يُرجع العدد الإجمالي للرسائل في جميع القوائم على النظام؛ وحقل msgtql يُرجع العدد الإجمالي للبايتات في جميع الرسائل في جميع القوائم على النظام.

MSG_STAT (خاص بلينكس)
    إرجاع بنية msqid_ds كما في IPC_STAT. ومع ذلك، فإن الوسيطة msqid ليست معرف قائمة، بل هي فهرس في المصفوفة الداخلية للنواة التي تحتفظ بمعلومات حول جميع قوائم الرسائل على النظام.

MSG_STAT_ANY (خاص بلينكس، منذ لينكس 4.17)
    إرجاع بنية msqid_ds كما في MSG_STAT. ومع ذلك، لا يتم التحقق من msg_perm.mode للوصول للقراءة لـ msqid مما يعني أن أي مستخدم يمكنه استخدام هذه العملية (تماماً كما يمكن لأي مستخدم قراءة /proc/sysvipc/msg للحصول على نفس المعلومات).

قيمة الإرجاع
عند النجاح، تُرجع IPC_STAT و IPC_SET و IPC_RMID 0. عملية IPC_INFO أو MSG_INFO الناجحة تُرجع فهرس أعلى إدخال مستخدم في المصفوفة الداخلية للنواة التي تسجل معلومات حول جميع قوائم الرسائل. (يمكن استخدام هذه المعلومات مع عمليات MSG_STAT أو MSG_STAT_ANY المتكررة للحصول على معلومات حول جميع القوائم على النظام.) عملية MSG_STAT أو MSG_STAT_ANY الناجحة تُرجع معرف القائمة التي تم إعطاء فهرسها في msqid.

عند الفشل، يتم إرجاع -1 وتعيين errno للإشارة إلى الخطأ.

الأخطاء

EACCES
    الوسيطة op تساوي IPC_STAT أو MSG_STAT، لكن العملية المستدعية لا تملك إذن قراءة على قائمة الرسائل msqid، ولا تملك القدرة CAP_IPC_OWNER في مساحة المستخدم التي تحكم مساحة IPC الخاصة بها.

EFAULT
    الوسيطة op لها القيمة IPC_SET أو IPC_STAT، لكن العنوان المشار إليه بواسطة buf غير قابل للوصول.

EIDRM
    حُذف طابور الرسائل.

EINVAL
    قيمة غير صالحة لـ op أو msqid. أو: لعملية MSG_STAT، قيمة الفهرس المحددة في msqid تشير إلى فتحة مصفوفة غير مستخدمة حالياً.

EPERM
    الوسيطة op لها القيمة IPC_SET أو IPC_RMID، لكن معرف المستخدم الفعال للعملية المستدعية ليس المنشئ (كما هو موجود في msg_perm.cuid) أو المالك (كما هو موجود في msg_perm.uid) لقائمة الرسائل، والمستدعي ليس مميزاً (لينكس: لا يمتلك القدرة CAP_SYS_ADMIN).

EPERM
    تمت محاولة (IPC_SET) لزيادة msg_qbytes فوق المعامل النظامي MSGMNB، لكن المستدعي ليس مميزاً (لينكس: لا يمتلك القدرة CAP_SYS_RESOURCE).

المعايير
POSIX.1-2024 XSI.

التاريخ
SVr4, SUSv1, POSIX.1-2001 XSI.

تمت كتابة عدة حقول في struct msqid_ds كنوع short تحت لينكس 2.2 وأصبحت long تحت لينكس 2.4. للاستفادة من هذا، يكفي إعادة الترجمة تحت glibc-2.1.91 أو أحدث. (تميز النواة بين الاستدعاءات القديمة والجديدة بواسطة علامة IPC_64 في op.)

ملاحظات
تُستخدم عمليات IPC_INFO و MSG_STAT و MSG_INFO بواسطة برنامج ipcs(1) لتوفير معلومات حول الموارد المخصصة. في المستقبل، قد يتم تعديل هذه أو نقلها إلى واجهة نظام ملفات /proc.

انظر أيضًا
msgget(2), msgrcv(2), msgsnd(2), capabilities(7), mq_overview(7), sysvipc(7)

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

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

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