SHMCTL

Manuel du programmeur Linux (2)
7 février 2014

---

 

NOM

shmctl - Contrôler la mémoire partagée System V  

SYNOPSIS

#include <sys/ipc.h>
#include <sys/shm.h>

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

DESCRIPTION

shmctl() effectue l'opération de contrôle indiquée par cmd sur le segment de mémoire partagée System V 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 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 ou le propriétaire du segment, ou le superutilisateur. Le paramètre buf est ignoré.

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.

Consultez la description de /proc/sys/kernel/shm_rmid_forced dans proc(5).

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 maximal de segments */
    unsigned long shmseg; /* Nombre maximal de segments qu'un
                             processus peut attacher ;
                             pas utilisé par le noyau */
    unsigned long shmall; /* Nombre maximal 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. Consultez 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)

Renvoyer 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 (consultez 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 (consultez 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

L'inclusion de <sys/types.h> et <sys/ipc.h> n'est pas nécessaire sous Linux et n'est exigée par aucune version de POSIX. Cependant, certaines implémentations anciennes nécessitent l'inclusion de ces fichiers d'en-tête, et le SVID documente aussi leur inclusion. Les applications ayant pour but d'être portables pourraient inclure ces fichiers d'en-tête.

Les opérations IPC_INFO, SHM_STAT et SHM_INFO sont utilisées par le programme ipcs(1) 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.66 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

Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a <http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet perkamon <http://perkamon.alioth.debian.org/>.

Christophe Blaess <http://www.blaess.fr/christophe/> (1996-2003), Alain Portal <http://manpagesfr.free.fr/> (2003-2006). Julien Cristau et l'équipe francophone de traduction de Debian (2006-2009).

Veuillez signaler toute erreur de traduction en écrivant à <perkamon-fr@traduc.org>.

Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande « LC_ALL=C man <section> <page_de_man> ».

---

 

Index

NOM

SYNOPSIS

DESCRIPTION

VALEUR RENVOYÉE

ERREURS

CONFORMITÉ

NOTES

VOIR AUSSI

COLOPHON

TRADUCTION

---

This document was created by man2html, using the manual pages.
Time: 21:52:36 GMT, July 12, 2014