shmctl(2)

الاسم
shmctl - التحكم في الذاكرة المشتركة System V

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

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

int shmctl(int shmid, int op, struct shmid_ds *buf);

الوصف
shmctl() ينفذ عملية التحكم المحددة بواسطة op على مقطع الذاكرة المشتركة System V الذي يُعطى معرفه في shmid.

الوسيطة buf هي مؤشر إلى بنية shmid_ds، المُعرّفة في <sys/shm.h> كما يلي:

    struct shmid_ds {
        struct ipc_perm shm_perm;    /* Ownership and permissions */
        size_t          shm_segsz;   /* Size of segment (bytes) */
        time_t          shm_atime;   /* Last attach time */
        time_t          shm_dtime;   /* Last detach time */
        time_t          shm_ctime;   /* Creation time/time of last
                                        modification via shmctl() */
        pid_t           shm_cpid;    /* PID of creator */
        pid_t           shm_lpid;    /* PID of last shmat(2)/shmdt(2) */
        shmatt_t        shm_nattch;  /* # of current attaches */
        ...
    };

حقول بنية shmid_ds هي كما يلي:

shm_perm
    هذه بنية ipc_perm (انظر أدناه) تحدد أذونات الوصول على مقطع الذاكرة المشتركة.

shm_segsz
    حجم مقطع الذاكرة المشتركة بالبايت.

shm_atime
    وقت آخر استدعاء نظام shmat(2) الذي أرفق هذا المقطع.

shm_dtime
    وقت آخر استدعاء نظام shmdt(2) الذي فصل هذا المقطع.

shm_ctime
    وقت إنشاء المقطع أو وقت آخر عملية shmctl() IPC_SET.

shm_cpid
    معرف العملية التي أنشأت مقطع الذاكرة المشتركة.

shm_lpid
    معرف آخر عملية نفذت استدعاء نظام shmat(2) أو shmdt(2) على هذا المقطع.

shm_nattch
    عدد العمليات التي لديها هذا المقطع مُرفقًا.

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

    struct ipc_perm {
        key_t          __key;    /* Key supplied to shmget(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 + SHM_DEST and
                                    SHM_LOCKED flags */
        unsigned short __seq;    /* Sequence number */
    };

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

البتات 0100 و 0010 و 0001 (بتات التنفيذ) غير مستخدمة من قبل النظام. (ليس من الضروري الحصول على إذن تنفيذ على مقطع لتنفيذ استدعاء shmat(2) مع العلم SHM_EXEC.)

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

IPC_STAT
    نسخ المعلومات من بنية بيانات النواة المرتبطة بـ shmid إلى بنية shmid_ds المشار إليها بواسطة buf. يجب أن يكون لدى المستدعي إذن قراءة على مقطع الذاكرة المشتركة.

IPC_SET
    كتابة قيم بعض أعضاء بنية shmid_ds المشار إليها بواسطة buf إلى بنية بيانات النواة المرتبطة بمقطع الذاكرة المشتركة هذا، مع تحديث العضو shm_ctime الخاص به أيضًا.

    الحقول التالية تُحدّث: shm_perm.uid و shm_perm.gid و (أقل 9 بتات أهمية من) shm_perm.mode.

    يجب أن يتطابق UID الفعّال للعملية المستدعية مع المالك (shm_perm.uid) أو المنشئ (shm_perm.cuid) لمقطع الذاكرة المشتركة، أو يجب أن يكون المستدعي متميزًا.

IPC_RMID
    وضع علامة على المقطع ليتم تدميره. سيتم تدمير المقطع فعليًا فقط بعد أن تفصله آخر عملية (أي عندما يكون العضو shm_nattch في البنية المرتبطة shmid_ds صفرًا). يجب أن يكون المستدعي هو المالك أو المنشئ للمقطع، أو أن يكون متميزًا. الوسيطة buf تُتجاهل.

    إذا تم وضع علامة على مقطع للتدمير، فسيتم تعيين العلم (غير القياسي) SHM_DEST لحقل shm_perm.mode في بنية البيانات المرتبطة التي يتم استردادها بواسطة IPC_STAT.

    يجب على المستدعي أن يضمن تدمير المقطع في النهاية؛ وإلا فإن صفحاته التي تم جلبها ستبقى في الذاكرة أو المبادلة.

    انظر أيضًا وصف /proc/sys/kernel/shm_rmid_forced في proc(5).

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

        struct shminfo {
            unsigned long shmmax; /* Maximum segment size */
            unsigned long shmmin; /* Minimum segment size;
                                     always 1 */
            unsigned long shmmni; /* Maximum number of segments */
            unsigned long shmseg; /* Maximum number of segments
                                     that a process can attach;
                                     unused within kernel */
            unsigned long shmall; /* Maximum number of pages of
                                     shared memory, system-wide */
        };

    يمكن تغيير إعدادات shmmni و shmmax و shmall عبر ملفات /proc التي تحمل الاسم نفسه؛ انظر proc(5) للتفاصيل.

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

        struct shm_info {
            int           used_ids; /* # of currently existing
                                       segments */
            unsigned long shm_tot;  /* Total number of shared
                                       memory pages */
            unsigned long shm_rss;  /* # of resident shared
                                       memory pages */
            unsigned long shm_swp;  /* # of swapped shared
                                       memory pages */
            unsigned long swap_attempts;
                                    /* Unused since Linux 2.4 */
            unsigned long swap_successes;
                                    /* Unused since Linux 2.4 */
        };

SHM_STAT (خاص بلينكس)
    إرجاع بنية shmid_ds كما في IPC_STAT. ومع ذلك، فإن وسيط shmid ليس معرف مقطع، بل هو فهرس في المصفوفة الداخلية للنواة التي تحتفظ بمعلومات حول جميع مقاطع الذاكرة المشتركة على النظام.

SHM_STAT_ANY (خاص بلينكس، منذ لينكس 4.17)
    إرجاع بنية shmid_ds كما في SHM_STAT. ومع ذلك، لا يتم التحقق من shm_perm.mode لحق الوصول للقراءة لـ shmid، مما يعني أن أي مستخدم يمكنه استخدام هذه العملية (تماماً كما يمكن لأي مستخدم قراءة /proc/sysvipc/shm للحصول على نفس المعلومات).

يمكن للمستدعي منع أو السماح بمبادلة مقطع ذاكرة مشتركة بقيم op التالية:

SHM_LOCK (خاص بلينكس)
    منع مبادلة مقطع الذاكرة المشتركة. يجب على المستدعي جلب أي صفحات مطلوب وجودها بعد تمكين القفل. إذا تم قفل مقطع، فسيتم تعيين العلم (غير القياسي) SHM_LOCKED لحقل shm_perm.mode في بنية البيانات المرتبطة المسترجعة بواسطة IPC_STAT.

SHM_UNLOCK (خاص بلينكس)
    فتح قفل المقطع، مما يسمح بمبادلته للخارج.

قبل لينكس 2.6.10، فقط عملية مميزة يمكنها استخدام SHM_LOCK و SHM_UNLOCK. منذ لينكس 2.6.10، يمكن لعملية غير مميزة استخدام هذه العمليات إذا كان معرف المستخدم الفعال الخاص بها يطابق معرف المستخدم المالك أو المنشئ للمقطع، و (لـ SHM_LOCK) تقع كمية الذاكرة المراد قفلها ضمن حد المورد RLIMIT_MEMLOCK (انظر setrlimit(2)).

قيمة الإرجاع
عملية IPC_INFO أو SHM_INFO الناجحة تُرجع فهرس أعلى إدخال مستخدم في المصفوفة الداخلية للنواة التي تسجل معلومات حول جميع مقاطع الذاكرة المشتركة. (يمكن استخدام هذه المعلومات مع عمليات SHM_STAT أو SHM_STAT_ANY المتكررة للحصول على معلومات حول جميع مقاطع الذاكرة المشتركة على النظام.) عملية SHM_STAT الناجحة تُرجع معرف مقطع الذاكرة المشتركة الذي تم إعطاء فهرسه في shmid. العمليات الأخرى تُرجع 0 عند النجاح.

عند الخطأ، تُعاد القيمة -1، ويُضبط errno للإشارة إلى الخطأ.

الأخطاء

EACCES
    يتم طلب IPC_STAT أو SHM_STAT و shm_perm.mode لا يسمح بحق الوصول للقراءة لـ shmid، ولا تمتلك العملية المستدعية القدرة CAP_IPC_OWNER في مساحة المستخدم التي تحكم مساحة IPC الخاصة بها.

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

EIDRM
    يشير shmid إلى معرف مزال.

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

ENOMEM
    (منذ لينكس 2.6.9)، تم تحديد SHM_LOCK وكان حجم المقطع المراد قفله يعني أن إجمالي البايتات في مقاطع الذاكرة المشتركة المقفلة سيتجاوز الحد لمعرف المستخدم الحقيقي للعملية المستدعية. يتم تعريف هذا الحد بواسطة حد المورد الناعم RLIMIT_MEMLOCK (انظر setrlimit(2)).

EOVERFLOW
    يتم محاولة IPC_STAT، وقيمة GID أو UID كبيرة جداً بحيث لا يمكن تخزينها في البنية المشار إليها بواسطة buf.

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

    أو (قبل لينكس 2.6.9)، تم تحديد SHM_LOCK أو SHM_UNLOCK، ولكن العملية لم تكن مميزة (لينكس: لم تمتلك القدرة CAP_IPC_LOCK). (منذ لينكس 2.6.9، يمكن أن يحدث هذا الخطأ أيضًا إذا كان RLIMIT_MEMLOCK هو 0 والمستدعي غير مميز.)

الإصدارات
يسمح لينكس لعملية بوصل (shmat(2)) مقطع ذاكرة مشتركة تم وضع علامة حذف عليه بالفعل باستخدام shmctl(IPC_RMID). هذه الميزة غير متوفرة في تطبيقات UNIX الأخرى؛ يجب على التطبيقات المحمولة تجنب الاعتماد عليها.

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

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

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

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

انظر أيضًا
mlock(2), setrlimit(2), shmget(2), shmop(2), capabilities(7), sysvipc(7)

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

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

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