NOM
shmctl - Contrôler la mémoire partagée
SYNOPSIS
#include <sys/ipc.h>
#include <sys/shm.h>
int shmctl(int shmid, int cmd, struct shmid_ds *buf);
shmctl() effectue l’opération de contrôle indiquée par cmd sur le
segment de mémoire partagée identifié par shmid.
L’argument buf est un pointeur sur une structure shmid_ds, définie dans
<sys/shm.h> comme suit :
struct shmid_ds {
struct ipc_perm shm_perm; /* Propriétaire et permissions */
size_t shm_segsz; /* Taille segment en octets */
time_t shm_atime; /* Heure dernier attachement */
time_t shm_dtime; /* Heure dernier détachement */
time_t shm_ctime; /* Heure dernier changement */
pid_t shm_cpid; /* PID du créateur */
pid_t shm_lpid; /* PID du dernier shmat(2) /
shmdt(2) */
shmatt_t shm_nattch; /* Nombre d’attachements actuels */
...
};
La structure ipc_perm est définie dans <sys/ipc.h> de la façon suivante
(les champs en gras peuvent être modifiés 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 + attributs
SHM_DEST et SHM_LOCKED */
unsigned short __seq; /* Numéro de séquence */
};
Les valeurs autorisées pour cmd sont :
IPC_STAT Copier dans la structure shmid_ds pointée par buf la
structure de données du noyau concernant shmid. Le processus
appelant doit avoir des privilèges de lecture sur le jeu de
sémaphores
IPC_SET Écrire la valeur de certains champs de la structure shmid_ds
pointée par buf dans la structure du noyau représentant ce
segment de mémoire partagée, en mettant à jour le champ
shm_ctime. Les champs suivants peuvent être mis à jour :
shm_perm.uid, shm_perm.gid et les 9 bits de poids faible de
shm_perm.mode. L’UID effectif du processus appelant doit être
soit celui du propriétaire (shm_perm.uid) soit celui du
créateur (shm_perm.cuid) du segment partagé, ou bien
l’appelant doit être privilégié.
IPC_RMID Marquer un segment comme prêt pour la destruction. Il sera
détruit effectivement après le dernier détachement (quand le
membre shm_nattch de la structure shmid_ds associée vaudra
zéro). L’appelant doit être le créateur du segment, son
propriétaire, ou le superutilisateur. Si un segment est
marqué pour destruction, le drapeau (non standard) SHM_DEST
sera levé dans le champ shm_perm.mode de la structure de
données associée récupérée par IPC_STAT.
L’appelant doit s’assurer que le segment sera bien détruit. Autrement,
les pages qui ont été allouées resteront indéfiniment en mémoire ou en
swap.
IPC_INFO (spécifique à Linux)
Fournir des informations sur les limites et paramètres du
système concernant la mémoire partagée dans la structure
pointée par buf. Cette structure est de type shminfo (ce qui
nécessite un transtypage), qui est défini dans <sys/shm.h> si
la macro _GNU_SOURCE est définie :
struct shminfo {
unsigned long shmmax; /* Taille maximum de segment */
unsigned long shmmin; /* Taille minimum de segment ;
toujours 1 */
unsigned long shmmni; /* Nombre maximum de segments */
unsigned long shmseg; /* Nombre maximum de segments qu’un
processus peut attacher ;
pas utilisé par le noyau */
unsigned long shmall; /* Nombre maximum de pages de
mémoire partagée sur le
système */
};
Les paramètres shmmni, shmmax et shmall peuvent être modifiés
via les fichiers du même nom dans /proc. Voir proc(5) pour
plus de détails.
SHM_INFO (spécifique à Linux)
Fournir une structure shm_info contenant des informations sur
les ressources système utilisées par des segments de mémoire
partagée. Cette structure est définie dans <sys/shm.h> si la
macro _GNU_SOURCE est définie :
struct shm_info {
int used_ids; /* Nombre de segments
actuellement existants */
unsigned long shm_tot; /* Nombre total de pages de
mémoire partagée */
unsigned long shm_rss; /* Nombre de pages de mémoire
partagée actuellement en RAM */
unsigned long shm_swp; /* Nombre de pages de mémoire
partagée actuellement en swap */
unsigned long swap_attempts;
/* Non utilisé depuis Linux 2.4 */
unsigned long swap_successes;
/* Non utilisé depuis Linux 2.4 */
};
SHM_STAT (spécifique à Linux)
Renvoie une structure shmid_ds comme pour IPC_STAT.
Cependant, l’argument shmid n’est pas l’identifiant d’un
segment, mais un indice dans la table interne du noyau qui
contient les informations sur tous les segments de mémoire
partagée du système.
L’appelant peut empêcher ou autoriser le noyau à évincer un segment de
mémoire partagée en swap avec les valeurs suivantes de cmd :
SHM_LOCK (spécifique à Linux)
Empêcher le segment d’être évincé en swap. L’appelant doit
consulter chaque page concernée après avoir effectué le
verrouillage pour s’assurer qu’elle est bien présente en
mémoire. Si un segment est verrouillé, le drapeau (non
standard) SHM_LOCKED sera levé dans le champ shm_perm.mode de
la structure de données, récupérée avec IPC_STAT, associée au
segment.
SHM_UNLOCK (spécifique à Linux)
Déverrouiller le segment, ce qui autorise son swapping.
Dans les noyaux antérieurs à 2.6.10, seul un processus privilégié
pouvait utiliser SHM_LOCK et SHM_UNLOCK. Depuis Linux 2.6.10, un
processus non privilégié peut utiliser ces opérations si son UID
effectif est celui du propriétaire ou du créateur du segment, et (pour
SHM_LOCK) la quantité de mémoire à verrouiller ne dépasse pas la limite
de ressource RLIMIT_MEMLOCK (voir setrlimit(2)).
VALEUR RENVOYÉE
Une opération IPC_INFO ou SHM_INFO réussie renvoie l’index de la plus
grande entrée utilisée dans le tableau interne du noyau contenant les
informations sur tous les segments de mémoire partagée. Cette
information peut être utilisée par des opérations SHM_STAT répétées
pour obtenir les informations sur tous les segments de mémoire partagée
du système. Une opération SHM_STAT réussie renvoie l’identifiant du
segment de mémoire partagée dont l’indice était fourni par shmid. Les
autres opérations renvoient 0 si elles réussissent.
En cas d’erreur, la valeur de retour est -1, et errno contient le code
d’erreur.
ERREURS
EACCES L’opération demandée est IPC_STAT ou SHM_STAT, mais
shm_perm.mode ne permet pas la lecture du segment shmid, et le
processus appelant n’a pas la capacité CAP_IPC_OWNER.
EFAULT cmd a la valeur IPC_SET ou IPC_STAT mais buf pointe en-dehors de
l’espace d’adressage accessible.
EIDRM shmid pointe sur un segment détruit.
EINVAL shmid n’est pas un identifiant correct, ou cmd n’est pas une
commande reconnue. Ou bien, pour l’opération SHM_STAT, l’indice
indiqué dans shmid correspond à un élément actuellement
inutilisé de la table.
ENOMEM (Depuis le noyau 2.6.9) L’opération SHM_LOCK a été demandée, et
la taille du segment à verrouiller entraînerait un dépassement
de la limite du nombre total d’octets de mémoire partagée
verrouillés pour l’UID réel du processus appelant. Cette limite
est la limite souple de ressource RLIMIT_MEMLOCK (voir
setrlimit(2)).
EOVERFLOW
L’opération demandée est IPC_STAT mais la valeur de GID ou d’UID
est trop grande pour être stockée dans la structure pointée par
buf.
EPERM On réclame IPC_SET ou IPC_RMID mais l’appelant n’est ni le
créateur du segment (trouvé dans shm_perm.cuid), ni le
propriétaire (trouvé dans shm_perm.uid) et le processus n’est
pas privilégié (sous Linux : n’a pas la capacité CAP_SYS_ADMIN.
Ou bien (pour les noyaux antérieurs à 2.6.9) soit SHM_LOCK soit
SHM_UNLOCK a été spécifié, mais le processus n’est pas
privilégié (sous Linux : n’a pas la capacité CAP_IPC_LOCK.
Depuis Linux 2.6.9, cette erreur peut également se produire si
la limite RLIMIT_MEMLOCK est 0, et l’appelant n’est pas
privilégié.
CONFORMITÉ
SVr4, POSIX.1-2001.
NOTES
Les opérations IPC_INFO, SHM_STAT et SHM_INFO sont utilisées par le
programme ipcs(8) pour fournir des informations sur les ressources
allouées. Ceci peut changer dans le futur, en utilisant une interface
sur le système de fichiers /proc.
Linux autorise un processus à attacher (shmat(2)) un segment de mémoire
partagée ayant été marqué pour suppression (avec shmctl(IPC_RMID).
Cette particularité n’est pas disponible sur d’autres variantes
d’Unix ; des applications portables ne devraient pas compter sur ce
comportement.
Divers champs de la structure shmid_ds étaient de type short sous Linux
2.2 et sont devenus des long sous Linux 2.4. Pour en tirer parti, une
recompilation sous glibc 2.1.91 ou ultérieure doit suffire. (Le noyau
distingue les anciens et nouveaux appels par un drapeau IPC_64 dans
cmd.)
VOIR AUSSI
mlock(2), setrlimit(2), shmget(2), shmop(2), capabilities(7), svipc(7)
COLOPHON
Cette page fait partie de la publication 3.23 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent être trouvées à l’adresse
http://www.kernel.org/doc/man-pages/.
TRADUCTION
Cette page de manuel a été traduite et mise à jour par Christophe
Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis par
Alain Portal <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
disposition sur http://manpagesfr.free.fr/.
Les mises à jour et corrections de la version présente dans Debian sont
directement gérées par Julien Cristau <jcristau@debian.org> et l’équipe
francophone de traduction de Debian.
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir accès à la version anglaise de ce document
en utilisant la commande « man -L C <section> <page_de_man> ».