ИМЯ¶

msgctl - операции для работы с сообщениями System V

СИНТАКСИС¶

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>

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

ОПИСАНИЕ¶

Вызов msgctl() выполняет операцию, заданную в cmd, над очередью сообщений 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) */
};

The fields of the msgid_ds structure are as follows:

msg_perm

This is an ipc_perm structure (see below) that specifies the access permissions on the message queue.

msg_stime

Время последнего вызова msgsnd(2).

msg_rtime

Время последнего вызова msgrcv(2).

msg_ctime

Time of creation of queue or time of last msgctl() IPC_SET operation.

msg_cbytes

Number of bytes in all messages currently on the message queue. This is a nonstandard Linux extension that is not specified in POSIX.

msg_qnum

Число сообщений, находящихся в данный момент в очереди сообщений.

msg_qbytes

Максимальная длина сообщения в байтах, разрешенная в очереди сообщений.

msg_lspid

ID процесса, выполнившего последний системный вызов msgsnd(2).

msg_lrpid

ID процесса, выполнившего последний системный вызов msgrcv(2).

Структура ipc_perm определена следующим образом (значения полей устанавливаются с помощью IPC_SET):

struct ipc_perm {


    key_t          __key;       /* ключ, передаваемый в msgget(2) */


    uid_t          uid;         /* эффективный UID владельца */


    gid_t          gid;         /* эффективный GID владельца */


    uid_t          cuid;        /* эффективный UID создателя */


    gid_t          cgid;        /* эффективный GID создателя */


    unsigned short mode;        /* права */


    unsigned short __seq;       /* порядковый номер */
};

The least significant 9 bits of the mode field of the ipc_perm structure define the access permissions for the message queue. The permission bits are as follows:

Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.

Возможные значения cmd:

IPC_STAT

Копирует информацию из структуры данных ядра, связанной с msqid, в структуру msqid_ds, расположенную по адресу buf. Вызывающий должен иметь права на чтение очереди сообщений.

IPC_SET

Write the values of some members of the msqid_ds structure pointed to by buf to the kernel data structure associated with this message queue, updating also its msg_ctime member.

The following members of the structure are updated: msg_qbytes, msg_perm.uid, msg_perm.gid, and (the least significant 9 bits of) msg_perm.mode.

The effective UID of the calling process must match the owner (msg_perm.uid) or creator (msg_perm.cuid) of the message queue, or the caller must be privileged. Appropriate privilege (Linux: the CAP_SYS_RESOURCE capability) is required to raise the msg_qbytes value beyond the system parameter MSGMNB.

IPC_RMID

Немедленно удаляет очередь сообщений, «будя» все процессы, ожидающие записи или чтения этой очереди (при этом возвращается ошибка, а переменная errno приобретает значение EIDRM). Вызывающий процесс должен иметь соответствующие привилегии или его эффективный идентификатор пользователя должен совпадать с идентификатором создателя или владельца очереди сообщений. Третий аргумент msgctl() в этом случае игнорируется.

IPC_INFO (есть только в Linux)

Возвращает параметры и информацию о системных максимальных значениях очереди сообщений в структуре, указанной в 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 (есть только в Linux)

Возвращает структуру msginfo, содержащую такую же информацию что и при операции IPC_INFO, за исключением того, что возвращаемые значения полей содержат информацию о системных ресурсах, потребляемых очередями сообщений: в поле msgpool возвращается количество очередей сообщений, которые в данный момент находятся в системе; в поле msgmap возвращается общее количество сообщений во всех очередях системы; в поле msgtql возвращается общее количество байт во всех сообщениях во всех очередях системы.

MSG_STAT (есть только в Linux)

Возвращает структуру msqid_ds как в операции IPC_STAT. Однако аргумент msqid является не уникальным идентификатором, а индексом во внутреннем массиве ядра, в котором содержится информации о всех очередях сообщений в системе.

MSG_STAT_ANY (есть только в Linux, начиная с Linux 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 записывается значение ошибки.

ОШИБКИ¶

В случае возникновения ошибки errno может принимать следующие значения:

EACCES

Значение аргумента cmd равно IPC_STAT или MSG_STAT, но вызывающий процесс не имеет прав на чтение очереди сообщений msqid, и не имеет мандата CAP_IPC_OWNER в пространстве имён пользователя, которое управляет его пространством имён IPC.

EFAULT

Значение аргумента cmd равно IPC_SET или IPC_STAT, но адрес, указанный в buf, недоступен.

EIDRM

Очередь сообщений была удалена.

EINVAL

Неверное значение cmd или msqid. Или: для операции MSG_STAT значение индекса, указанного в msqid, ссылается на слот массива, который в данный момент не используется.

EPERM

Значение аргумента cmd равно IPC_SET или IPC_RMID, но эффективный пользовательский идентификатор вызывающего процесса не равен идентификатору создателя (msg_perm.cuid) или владельца (msg_perm.uid) очереди сообщений, и вызывающий не имеет прав (Linux: не имеет мандата CAP_SYS_ADMIN).

EPERM

Была предпринята попытка (IPC_SET) увеличить msg_qbytes и нарушить границы системного параметра MSGMNB, но вызывающий не имеет прав (Linux: не имеет мандата CAP_SYS_RESOURCE).

СООТВЕТСТВИЕ СТАНДАРТАМ¶

POSIX.1-2001, POSIX.1-2008, SVr4.

ЗАМЕЧАНИЯ¶

Включение файлов <sys/types.h> и <sys/ipc.h> не требуется в Linux или любых версий POSIX. Однако, некоторые старые реализации требуют включения данных заголовочных файлов, и это также требуется по SVID. В приложениях, которые нужно перенести на такие старые системы, может потребоваться включить данных заголовочные файлы.

Операции IPC_INFO, MSG_STAT и MSG_INFO используются программой ipcs(1) для получения информации о выделенных ресурсах. В будущем для этого может быть задействован интерфейс файловой системы /proc.

Различные поля в struct msqid_ds, которые имели тип short в Linux 2.2, в Linux 2.4 теперь имеют тип long. Чтобы воспользоваться этим преимуществом достаточно пересобрать программу с glibc-2.1.91 или более новой версией. (Ядро различает старые и новые вызовы по флагу IPC_64 в cmd.)

СМ. ТАКЖЕ¶

msgget(2), msgrcv(2), msgsnd(2), capabilities(7), mq_overview(7), sysvipc(7)

ЗАМЕЧАНИЯ¶

Эта страница является частью проекта Linux man-pages версии 5.10. Описание проекта, информацию об ошибках и последнюю версию этой страницы можно найти по адресу https://www.kernel.org/doc/man-pages/.

ПЕРЕВОД¶

Русский перевод этой страницы руководства был сделан aereiae <aereiae@gmail.com>, Alexey <a.chepugov@gmail.com>, Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitriy S. Seregin <dseregin@59.ru>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, ITriskTI <ITriskTI@gmail.com>, Max Is <ismax799@gmail.com>, Yuri Kozlov <yuray@komyakino.ru>, Иван Павлов <pavia00@gmail.com> и Малянов Евгений Викторович <maljanow@outlook.com>

Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на man-pages-ru-talks@lists.sourceforge.net.