SHMCTL(2)

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;    /* Ownership and permissions */
        size_t          shm_segsz;   /* Size of segment (bytes) */
        time_t          shm_atime;   /* Last attach time */
        time_t          shm_dtime;   /* Last detach time */
        time_t          shm_ctime;   /* Creation time/time of last
                                        modification via shmctl() */
        pid_t           shm_cpid;    /* PID of creator */
        pid_t           shm_lpid;    /* PID of last shmat(2)/shmdt(2) */
        shmatt_t        shm_nattch;  /* No. of current attaches */
        ...
    };

The fields of the shmid_ds structure are as follows:

shm_perm
    This is an ipc_perm structure (see below) that specifies the access permissions on the shared memory segment.

shm_segsz
    Taille en octets du segment de mémoire partagée.

shm_atime
    Time of the last shmat(2) system call that attached this segment.

shm_dtime
    Time of the last shmdt(2) system call that detached tgis segment.

shm_ctime
    Time of creation of segment or time of the last shmctl() IPC_SET operation.

shm_cpid
    PID du processus ayant créé le segment de mémoire partagée.

shm_lpid
    ID of the last process that executed a shmat(2) or shmdt(2) system call on this segment.

shm_nattch
    Number of processes that have this segment attached.

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 */
    };

The least significant 9 bits of the mode field of the ipc_perm structure define the access permissions for the shared memory segment. The permission bits are as follows:
0400 | Lisible par l'utilisateur
0200 | Droit d'écriture pour l'utilisateur
0040 | Lisible par le groupe
0020 | Autorisation d'écriture pour le groupe
0004 | Lisible par les autres
0002 | Écrit par d'autres

Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. (It is not necessary to have execute permission on a segment in order to perform a shmat(2) call with the SHM_EXEC flag.)

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
    Write the values of some members of the shmid_ds structure pointed to by buf to the kernel data structure associated with this shared memory segment, updating also its shm_ctime member.

    The following fields are updated: shm_perm.uid, shm_perm.gid, and (the least significant 9 bits of) shm_perm.mode.

    The effective UID of the calling process must match the owner (shm_perm.uid) or creator (shm_perm.cuid) of the shared memory segment, or the caller must be privileged.

IPC_RMID
    Mark the segment to be destroyed. The segment will actually be destroyed only after the last process detaches it (i.e., when the shm_nattch member of the associated structure shmid_ds is zero). The caller must be the owner or creator of the segment, or be privileged. The buf argument is ignored.

    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.

SHM_STAT_ANY (Linux-specific, since Linux 4.17)
    Return a shmid_ds structure as for SHM_STAT. However, shm_perm.mode is not checked for read access for shmid, meaning that any user can employ this operation (just as any user may read /proc/sysvipc/shm to obtain the same information).

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
A successful IPC_INFO or SHM_INFO operation returns the index of the highest used entry in the kernel's internal array recording information about all shared memory segments. (This information can be used with repeated SHM_STAT or SHM_STAT_ANY operations to obtain information about all shared memory segments on the system.) A successful SHM_STAT operation returns the identifier of the shared memory segment whose index was given in shmid. Other operations return 0 on success.

En cas d'erreur, la valeur de retour est -1, et errno est défini de façon appropriée.

ERREURS

EACCES
    IPC_STAT or SHM_STAT is requested and shm_perm.mode does not allow read access for shmid, and the calling process does not have the CAP_IPC_OWNER capability in the user namespace that governs its IPC namespace.

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 is not a valid identifier, or cmd is not a valid command. Or: for a SHM_STAT or SHM_STAT_ANY operation, the index value specified in shmid referred to an array slot that is currently unused.

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É
POSIX.1-2001, POSIX.1-2008, SVr4.

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.

The IPC_INFO, SHM_STAT, and SHM_INFO operations are used by the ipcs(1) program to provide information on allocated resources. In the future, these may modified or moved to a /proc filesystem interface.

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), sysvipc(7)

COLOPHON
Cette page fait partie de la publication 5.10 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies et la dernière version de cette page peuvent être trouvées à l'adresse https://www.kernel.org/doc/man-pages/.

TRADUCTION
La traduction française de cette page de manuel a été créée par Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org> et David Prévot <david@tilapin.org>

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 (https://www.gnu.org/licenses/gpl-3.0.html) concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à debian-l10n-french@lists.debian.org.