الاسم¶

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 أذونات الوصول إلى قائمة انتظار الرسائل. بتات الأذونات هي كما يلي:

البتات 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 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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