MSGCTL(2)

NOM
msgctl - Contrôler les messages

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

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

DESCRIPTION
msgctl() permet d'effectuer l'opération indiquée par cmd sur la file de messages ayant l'identificateur msqid.

La structure de données msqid_ds est définie dans <sys/msg.h> de la manière suivante :
struct msqid_ds {
    struct ipc_perm msg_perm;     /* Appartenance et permissions */
    time_t          msg_stime;    /* Heure du dernier msgsnd(2) */
    time_t          msg_rtime;    /* Heure du dernier msgrcv(2) */
    time_t          msg_ctime;    /* Heure de la dernière modif */
    unsigned long   __msg_cbytes; /* Nombre actuel d'octets dans la
                                     file (non-standard) */
    msgqnum_t       msg_qnum;     /* Nombre actuel de messages dans
                                     la file */
    msglen_t        msg_qbytes;   /* Nombre maximum d'octets
                                     autorisés dans la file */
    pid_t           msg_lspid;    /* PID du dernier msgsnd(2) */
    pid_t           msg_lrpid;    /* PID du dernier msgrcv(2) */
};

La structure ipc_perm est définie dans <sys/ipc.h> de la manière suivante (les champs mis en évidence sont configurables en utilisant IPC_SET):

struct ipc_perm {
    key_t key;            /* Clé fournie à msgget(2) */
    uid_t uid;            /* UID effectif du propriétaire */
    gid_t gid;            /* GID effectif du propriétaire */
    uid_t cuid;           /* UID effectif du créateur */
    gid_t cgid;           /* GID effectif du créateur */
    unsigned short mode;  /* Permissions */
    unsigned short seq;   /* Numéro de séquence */
};

Les valeurs possibles de cmd sont :

IPC_STAT
    Copier les informations depuis la structure de données du noyau associée à msqid dans la structure msqid_ds pointée par buf. L'appelant doit avoir des privilèges d'accès en lecture sur la file de messages.

IPC_SET
    Écrire la valeur de certains champs de la structure msqid_ds pointée par buf dans la structure de données du noyau associée à cette file de messages, en mettant à jour le champ msg_ctime. Les champs suivants de la structure peuvent être mis à jour : msg_qbytes, msg_perm.uid, msg_perm.gid et (les 9 bits poids faibles de) msg_perm.mode. L'UID effectif du processus appelant doit être celui du propriétaire (msg_perm.uid) ou celui du créateur (msg_perm.cuid) de la file de messages ou l'appelant doit être privilégié. Des privilèges appropriés (sous Linux, la capacité CAP_IPC_RESOURCE) sont nécessaires pour augmenter la valeur de msg_qbytes au-dessus de la constante système MSGMNB. Sur un système Linux, cela nécessite la capacité CAP_SYS_RESOURCE.

IPC_RMID
    Effacer immédiatement la file de messages, en réveillant tous les processus écrivains et lecteurs en attente. Ils obtiendront un code d'erreur, et errno aura la valeur EIDRM. Le processus appelant doit avoir les privilèges associés ou bien son UID effectif doit être celui du créateur ou du propriétaire de la file de messages.

IPC_INFO (Spécifique à Linux)
    Renvoyer les informations sur les limites de files de messages à l'échelle du système et les paramètres dans une structure pointée par buf. Cette structure est du type msginfo (aussi, un transtypage est nécessaire), définie dans <sys/msg.h> si la macro de test de fonctionnalités _GNU_SOURCE est définie :
    struct msginfo {
        int msgpool; /* Taille en octets du tampon utilisé pour
                        stocker les données messages ; inutilisé */
        int msgmap;  /* Nombre maximum d'entrées dans la carte de
                        messages ; inutilisé */
        int msgmax;  /* Nombre maximum d'octets qui peuvent
                        être écrit dans un message */
        int msgmnb;  /* Nombre maximum d'octets qui peuvent être écrits
                        dans une file ; utilisé pour initialiser msg_qbytes
                        lors de la création de la file (msgget(2)) */
        int msgmni;  /* Nombre maximum de files de messages */
        int msgssz;  /* Taille du segment de message ; inutilisé */
        int msgtql;  /* Nombre maximum de messages dans toutes les files
                        du système ; inutilisé */
        unsigned short int msgseg;
                     /* Nombre maximum de segments ; inutilisé */
    };
    Les réglages msgmni, msgmax et msgmnb peuvent être modifié via les fichiers /proc de même nom ; voir proc(5) pour plus de détails.

MSG_INFO (Spécifique à Linux)
    Renvoie une structure msginfo contenant les mêmes informations que pour IPC_INFO, excepté que les champs suivants sont renvoyés avec une information relative aux ressources système consommées par les files de messages : le champ msgpool renvoie le nombre de files de messages qui existent actuellement sur le système ; le champ msgmap renvoie le nombre total de messages dans toutes les files du système ; et le champ msgtql renvoie le nombre total d'octets de tous les messages de toutes les files du système.

MSG_STAT (Spécifique à Linux)
    Renvoie une structure msqid_ds comme pour IPC_STAT. Toutefois, l'argument msqid n'est pas un identifiacateur de file, mais plutôt un index dans un tableau interne au noyau qui contient des informations sur toutes les files de messages sur le système.

VALEUR RENVOYÉE
S'ils réussissent, IPC_STAT, IPC_SET et IPC_RMID renvoie 0. Une opération IPC_INFO ou MSG_INFO réussie renvoie l'index le plus grand de l'entrée utilisée dans le tableau interne du noyau contenant l'information sur toutes les files de messages. (Cette information peut être utilisée avec des opérations MSG_STAT répétées pour obtenir les informations sur toutes les files de messages du système). Une opération MSG_STAT réussie renvoie l'indentificateur de la file dont l'index a été donné à msqid. msgctl() S'ils échouent, -1 est renvoyé auquel cas errno contient le code d'erreur.

ERREURS

EACCES
    L'argument cmd réclame l'opération IPC_STAT ou MSG_STAT, mais le processus appelant n'a pas d'accès en lecture sur la file de messages msqid, et n'a pas la capacité CAP_IPC_OWNER.

EFAULT
    L'argument cmd réclame l'opération IPC_SET ou IPC_STAT mais buf pointe en dehors de l'espace d'adressage accessible.

EIDRM
    La file de messages a déjà été supprimée.

EINVAL
    cmd ou msqid ont une valeur illégale. Ou, pour une opération MSG_STAT, la valeur d'index spécifiée dans msqid fait référencé à un emplacement du tableau qui n'est pas actuellement utilisé.

EPERM
    L'argument cmd réclame l'opération IPC_SET ou IPC_RMID mais l'UID effectif du processus appelant n'est pas le créateur (comme indiqué dans msg_perm.cuid) ou le propriétaire (comme indiqué dans msg_perm.uid) de la file de message, et le processus n'est pas privilégié (sous Linux, il n'a pas la capacité CAP_SYS_ADMIN).

CONFORMITÉ
SVr4, POSIX.1-2001.

NOTES
Les opérations IPC_INFO, MSG_STAT et MSG_INFO sont utilisées par le programme ipcs(8) pour fournir des informations sur les ressources allouées. Dans le futur, celles-ci seront modifiées ou déplacées vers l'interface du système de fichier /proc. Divers champs de la structure struct msqid_ds étaient des short sous Linux 2.2 et sont devenus long sous Linux 2.4. Pour en profiter, une recompilation avec la glibc 2.1.91 ou ultérieure devrait suffire. (Le noyau distingue les appels anciens et nouveaux par un drapeau IPC_64 dans cmd).

VOIR AUSSI
msgget(2), msgrcv(2), msgsnd(2), capabilities(7), mq_overview(7), svipc(7)

TRADUCTION

Ce document est une traduction réalisée par Christophe Blaess <http://www.blaess.fr/christophe/> le 14 octobre 1996 et révisée le 22 décembre 2007.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 2 msgctl ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.