MSGCTL
Section : Manuel du programmeur Linux (
2)
Mise à jour de la version anglaise : 20 mai 2008
Index
Menu principal
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'identifiant
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 façon 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 pour
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 faible 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.
- 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 de 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 kibioctets du tampon utilisé pour
stocker les données messages ;
inutilisé par le noyau */
int msgmap; /* Nombre maximum d'entrées dans la table des
messages ; inutilisé dans le noyau */
int msgmax; /* Nombre maximum d'octets pouvant
être écrit dans un message */
int msgmnb; /* Nombre maximum d'octets pouvant ê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é par le noyau */
int msgtql; /* Nombre maximum de messages dans toutes les files
du système ; inutilisé dans le noyau */
unsigned short int msgseg;
/* Nombre maximum de segments ;
inutilisé par le noyau */
};
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 identifiant de file, mais plutôt un index dans un tableau
interne au noyau qui contient des informations sur toutes les files de
messages du 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
est renseignée en conséquence.
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 messages, 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 de type
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 17 juillet 2008.
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.
Index
- NOM
-
- SYNOPSIS
-
- DESCRIPTION
-
- VALEUR RENVOYÉE
-
- ERREURS
-
- CONFORMITÉ
-
- NOTES
-
- VOIR AUSSI
-
- TRADUCTION
-
Dernière mise à jour : 17 juillet 2008