.\" -*- coding: UTF-8 -*- .\" Copyright (C) 2002, 2020 Michael Kerrisk .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" %%%LICENSE_END .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH SHM_OPEN 3 "1 novembre 2020" Linux "Manuel du programmeur Linux" .SH NOM shm_open, shm_unlink \- Créer, ouvrir ou supprimer des objets en mémoire partagée POSIX .SH SYNOPSIS \fB#include \fP .br \fB#include \fP /* Pour les constantes des modes */ .br \fB#include \fP /* Pour les constantes O_* */ .PP \fBint shm_open(const char *\fP\fInom\fP\fB, int \fP\fImasque\fP\fB, mode_t \fP\fImode\fP\fB);\fP .PP \fBint shm_unlink(const char *\fP\fInom\fP\fB);\fP .PP Éditer les liens avec \fI\-lrt\fP. .SH DESCRIPTION La fonction \fBshm_open\fP() crée et ouvre un nouvel objet en mémoire partagée POSIX, ou ouvre un objet existant. Il s'agit d'un descripteur utilisable par des processus indépendants pour projeter la même région mémoire à l'aide de \fBmmap\fP(2). La fonction \fBshm_unlink\fP() réalise l'opération inverse en supprimant l'objet créé précédemment par \fBshm_open\fP(). .PP .\" glibc allows the initial slash to be omitted, and makes .\" multiple initial slashes equivalent to a single slash. .\" This differs from the implementation of POSIX message queues. .\" glibc allows subdirectory components in the name, in which .\" case the subdirectory must exist under /dev/shm, and allow the .\" required permissions if a user wants to create a shared memory .\" object in that subdirectory. Le fonctionnement de \fBshm_open\fP() est analogue à celui de \fBopen\fP(2). \fInom\fP indique l'objet en mémoire partagée à créer ou ouvrir. Pour un fonctionnement portable, un objet en mémoire partagée doit être identifié par un nom au format \fI/un_nom\fP\ ; c'est\-à\-dire une chaîne terminée par un octet de valeur zéro d'au plus \fBNAME_MAX\fP (c'est\-à\-dire 255) caractères, et commençant par une barre oblique («\ /\ ») suivie d'un caractère ou plus, ces derniers n'étant pas des barres obliques. .PP \fImasque\fP est un masque de bits associant à l'aide d'un OU logique une et une seule des deux constantes \fBO_RDONLY\fP ou \fBO_RDWR\fP et un ou plusieurs des attributs décrits ci\-après\ : .TP \fBO_RDONLY\fP Ouvrir l'objet en lecture seule. Un tel objet ne pourra être projeté en mémoire avec \fBmmap\fP(2) qu'avec un accès en lecture (\fBPROT_READ\fP). .TP \fBO_RDWR\fP Ouvrir l'objet en lecture et écriture. .TP \fBO_CREAT\fP .\" In truth it is actually the filesystem IDs on Linux, but these .\" are nearly always the same as the effective IDs. (MTK, Jul 05) Créer l'objet en mémoire partagée s'il n'existe pas. L'utilisateur et le groupe propriétaires de l'objet proviennent des ID effectifs du processus appelant, et les bits de permission sont définis en fonction des 9\ bits de poids faible de \fImode\fP, excepté que les bits qui sont définis dans le masque de mode de fichier pour la création du processus (consultez \fBumask\fP(2)) sont effacés pour le nouvel objet. Un jeu de constantes de macroutilisables pour définir le \fImode\fP est décrit dans \fBopen\fP(2) (les définitions symboliques de ces constantes peuvent être obtenues en incluant \fI\fP). .IP Un nouvel objet en mémoire partagée a une taille initiale nulle — elle peut être définie avec \fBftruncate\fP(2). Les octets d'un objet en mémoire partagée nouvellement créé sont automatiquement initialisés à zéro. .TP \fBO_EXCL\fP Si \fBO_CREAT\fP était aussi précisé et si un objet en mémoire partagée avec le même \fInom\fP existait déjà, renvoyer une erreur. La vérification de l'existence de l'objet et sa création s'il n'existe pas sont réalisées de manière atomique. .TP \fBO_TRUNC\fP Si l'objet en mémoire partagée existe déjà, tronquer sa taille à zéro. .PP Les définitions des valeurs de ces attributs peuvent être obtenues en incluant \fI\fP. .PP Si elle réussit, la fonction \fBshm_open\fP() renvoie un nouveau descripteur de fichierréférençant l'objet en mémoire partagée. Ce descripteur sera le plus petit numéro disponible dans la table des descripteurs du processus. L'attribut \fBFD_CLOEXEC\fP (consultez \fBfcntl\fP(2)) sera activé pour le descripteur de fichier. .PP Le descripteur de fichier est utilisé normalement pour les appels ultérieurs à \fBftruncate\fP(2) (pour un objet nouvellement créé) et \fBmmap\fP(2). Après un appel à \fBmmap\fP(2) le descripteur peut être fermé sans affecter la projection mémoire. .PP Le fonctionnement de \fBshm_unlink\fP() est analogue à celui de \fBunlink\fP(2)\ : elle supprime le nom d'un objet en mémoire partagée, et, lorsque tous les processus ont supprimé leur projection en mémoire de l'objet considéré, libère et détruit le contenu de la portion de mémoire associée. Après un appel réussi à \fBshm_unlink\fP(), les tentatives d'appeler \fBshm_open\fP() avec le même \fInom\fP échoueront (sauf si \fBO_CREAT\fP est spécifié, auquel cas un nouvel objet distinct sera créé). .SH "VALEUR RENVOYÉE" S'il réussit, l'appel \fBshm_open\fP() renvoie un descripteur de fichier (un entier non négatif). S'il échoue, \fBshm_open\fP() renvoie\ \fB\-1\fP. \fBshm_unlink\fP() renvoie\ \fB0\fP s'il réussit ou\ \fB\-1\fP en cas d'erreur. .SH ERREURS En cas d'échec, \fIerrno\fP indique la cause de l'erreur. Les valeurs possibles de \fIerrno\fP sont les suivantes\ : .TP \fBEACCES\fP La permission d'utiliser \fBshm_unlink\fP() sur l'objet en mémoire partagée a été refusée. .TP \fBEACCES\fP L'utilisation de \fBshm_open\fP() pour ouvrir l'objet \fInom\fP dans le \fImode\fP spécifié a été refusée, ou \fBO_TRUNC\fP a été spécifié et l'appelant n'a pas les permissions d'écriture sur l'objet. .TP \fBEEXIST\fP \fBO_CREAT\fP et \fBO_EXCL\fP ont été spécifiés dans \fBshm_open\fP() et un objet de mémoire partagée du même \fInom\fP existe déjà. .TP \fBEINVAL\fP L'argument \fInom\fP de \fBshm_open\fP() n'était pas valable. .TP \fBEMFILE\fP La limite du nombre de descripteurs de fichiers par processus a été atteinte. .TP \fBENAMETOOLONG\fP La longueur du \fInom\fP dépasse \fBPATH_MAX\fP. .TP \fBENFILE\fP La limite du nombre total de fichiers ouverts pour le système entier a été atteinte. .TP \fBENOENT\fP Tentative d'ouvrir avec \fBshm_open\fP() un objet \fInom\fP qui n'existe pas, alors que l'attribut \fBO_CREAT\fP n'a pas été spécifié. .TP \fBENOENT\fP Tentative d'utiliser \fBshm_unlink\fP() sur un objet \fInom\fP qui n'existe pas. .SH VERSIONS Ces fonctions sont fournies depuis la glibc\ 2.2. .SH ATTRIBUTS Pour une explication des termes utilisés dans cette section, consulter \fBattributes\fP(7). .TS allbox; lbw24 lb lb l l l. Interface Attribut Valeur T{ \fBshm_open\fP(), \fBshm_unlink\fP() T} Sécurité des threads MT\-Safe locale .TE .sp 1 .SH CONFORMITÉ POSIX.1\-2001, POSIX.1\-2008. .PP POSIX.1\-2001 indique que le groupe propriétaire d'un objet en mémoire partagée nouvellement créé utilise soit l'ID de groupe du processus appelant, soit un «\ ID de groupe par défaut défini par le système\ ». POSIX.1\-2008 indique que le groupe propriétaire peut être défini soit avec l'ID de groupe du processus appelant, soit, si l'objet est visible dans le système de fichiers, avec l'ID de groupe du répertoire parent. .SH NOTES POSIX ne précise pas le comportement de la combinaison \fBO_RDONLY\fP et \fBO_TRUNC\fP. Sous Linux, la troncature aura lieu — cela n'est pas nécessairement le cas sous d'autres systèmes UNIX. .PP L'implémentation sous Linux des objets de mémoire partagée POSIX utilise un système de fichiers \fBtmpfs\fP(5) dédié, monté en principe sous \fI/dev/shm\fP. .SH EXEMPLES Les programmes ci\-dessous utilisent la mémoire partagée POSIX et des sémaphores non nommés POSIX pour échanger des données. Le programme «\ bounce\ » (qui doit être exécuté en premier) illustre le cas d'une chaîne placée en mémoire partagée par le programme «\ send\ ». Lorsque les données ont été modifiées, le programme «\ send\ » affiche le contenu de la mémoire partagée modifié. Voici un exemple d'exécution des deux programmes\ : .PP .in +4n .EX $ \fB./pshm_ucase_bounce /myshm &\fP [1] 270171 $ \fB./pshm_ucase_send /myshm bonjour\fP BONJOUR .EE .in .PP .\" Vous trouverez plus de détails à propos de ces programmes ci\-dessous. .SS "Source du programme\ : pshm_ucase.h" Ce fichier d'en\-tête est inclus par les deux programmes ci\-dessous. Sa principale fonction consiste à définir une structure qui sera imposée à l'objet en mémoire partagé entre les deux programmes. .PP .in +4n .EX #include #include #include #include #include #include #include #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e } while (0) #define BUF_SIZE 1024 /* Taille maximale de la chaîne échangée */ /* Définir une structure qui sera imposée à l'objet en mémoire partagée */ struct shmbuf { sem_t sem1; /* Sémaphore POSIX non nommé */ sem_t sem2; /* Sémaphore POSIX non nommé */ size_t cnt; /* Nombre d'octets utilisés dans \(aqbuf\(aq */ char buf[BUF_SIZE]; /* Données en cours de transfert */ }; .EE .in .\" .SS "Source programme\ : pshm_ucase_bounce.c" Le programme «\ bounce\ » crée un nouvel objet en mémoire partagée avec le nom spécifié comme argument de la ligne de commande et le dimensionne de manière à correspondre à la taille de la structure \fIshmbuf\fP définie dans le fichier d'en\-tête. Il projette ensuite l'objet dans l'espace d'adressage du processus et initialise deux sémaphores POSIX à\ \fB0\fP à l'intérieur de l'objet. .PP Une fois le premier sémaphore posté par le programme «\ send\ », le programme «\ bounce\ » met en capitales les données placées en mémoire par le programme «\ send\ », puis poste le second sémaphore pour indiquer au programme «\ send\ » qu'il peut maintenant accéder à la mémoire partagée. .PP .in +4n .EX /* pshm_ucase_bounce.c Licensed under GNU General Public License v2 or later. */ #include #include "pshm_ucase.h" int main(int argc, char *argv[]) { if (argc != 2) { fprintf(stderr, "Usage: %s /shm\-path\en", argv[0]); exit(EXIT_FAILURE); } char *shmpath = argv[1]; /* Créer l'objet en mémoire virtuelle et définir sa taille égale à celle de notre structure */ int fd = shm_open(shmpath, O_CREAT | O_EXCL | O_RDWR, S_IRUSR | S_IWUSR); if (fd == \-1) errExit("shm_open"); if (ftruncate(fd, sizeof(struct shmbuf)) == \-1) errExit("ftruncate"); /* Projeter l'objet dans l'espace d'adressage de l'appelant */ struct shmbuf *shmp = mmap(NULL, sizeof(*shmp), PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); if (shmp == MAP_FAILED) errExit("mmap"); /* Initialiser les sémaphores comme partagés entre processus avec une valeur de\ \fB0\fP */ if (sem_init(&shmp\->sem1, 1, 0) == \-1) errExit("sem_init\-sem1"); if (sem_init(&shmp\->sem2, 1, 0) == \-1) errExit("sem_init\-sem2"); /* Attendre que le sémaphore \(aqsem1\(aq soit posté par le processus pair avant de toucher à la mémoire partagée */ if (sem_wait(&shmp\->sem1) == \-1) errExit("sem_wait"); /* Convertir en capitales les données en mémoire partagée */ for (int j = 0; j < shmp\->cnt; j++) shmp\->buf[j] = toupper((unsigned char) shmp\->buf[j]); /* Poster \(aqsem2\(aq pour informer le processus pair qu'il peut maintenant accéder aux données modifiées en mémoire partagée */ if (sem_post(&shmp\->sem2) == \-1) errExit("sem_post"); /* Supprimer le lien avec l'objet en mémoire partagée. Cela ne posera pas de problème, même si le processus pair utilise encore l'objet, car ce dernier ne sera supprimé que lorsque tous les liens ouverts qui y font référence auront été fermés. */ shm_unlink(shmpath); exit(EXIT_SUCCESS); } .EE .in .\" .SS "Source du programme\ : pshm_ucase_send.c" Le programme «\ send\ » accepte deux arguments de ligne de commande\ : le nom d'un objet en mémoire partagée préalablement créé par le programme «\ bounce\ » et une chaîne à copier dans cet objet. .PP Le programme ouvre l'objet en mémoire partagée et le projette dans son espace d'adressage. Ensuite, il copie les données spécifiées à l'aide du second argument vers la mémoire partagée et poste le premier sémaphore pour informer le programme «\ bounce\ » qu'il peut maintenant accéder aux données. Lorsque le programme «\ bounce\ » a posté le second sémaphore, le programme «\ send\ » affiche le contenu de la mémoire partagée sur la sortie standard. .PP .in +4n .EX /* pshm_ucase_send.c Licensed under GNU General Public License v2 or later. */ #include #include "pshm_ucase.h" int main(int argc, char *argv[]) { if (argc != 3) { fprintf(stderr, "Usage: %s /shm\-path string\en", argv[0]); exit(EXIT_FAILURE); } char *shmpath = argv[1]; char *string = argv[2]; size_t len = strlen(string); if (len > BUF_SIZE) { fprintf(stderr, "La chaîne est trop longue\en"); exit(EXIT_FAILURE); } /* Ouvrir l'objet en mémoire partagée existant et projeter ce dernier dans l'espace d'adressage de l'appelant */ int fd = shm_open(shmpath, O_RDWR, 0); if (fd == \-1) errExit("shm_open"); struct shmbuf *shmp = mmap(NULL, sizeof(*shmp), PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); if (shmp == MAP_FAILED) errExit("mmap"); /* Copier les données dans l'objet en mémoire partagée */ shmp\->cnt = len; memcpy(&shmp\->buf, string, len); /* Informer le processus pair qu'il peut maintenant accéder à la mémoire partagée */ if (sem_post(&shmp\->sem1) == \-1) errExit("sem_post"); /* Attendre que le processus pair signale qu'il a fini d'accéder à la mémoire partagée */ if (sem_wait(&shmp\->sem2) == \-1) errExit("sem_wait"); /* Afficher les données modifiées en mémoire partagée sur la sortie standard */ write(STDOUT_FILENO, &shmp\->buf, len); write(STDOUT_FILENO, "\en", 1); exit(EXIT_SUCCESS); } .EE .in .SH "VOIR AUSSI" \fBclose\fP(2), \fBfchmod\fP(2), \fBfchown\fP(2), \fBfcntl\fP(2), \fBfstat\fP(2), \fBftruncate\fP(2), \fBmemfd_create\fP(2), \fBmmap\fP(2), \fBopen\fP(2), \fBumask\fP(2), \fBshm_overview\fP(7) .SH COLOPHON Cette page fait partie de la publication\ 5.10 du projet \fIman\-pages\fP 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/. .PP .SH TRADUCTION La traduction française de cette page de manuel a été créée par Christophe Blaess , Stéphan Rafin , Thierry Vignaud , François Micaux, Alain Portal , Jean-Philippe Guérard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas François , Florentin Duneau , Simon Paillard , Denis Barbier , David Prévot et Lucien Gentis . .PP Cette traduction est une documentation libre ; veuillez vous reporter à la .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License version 3 .UE concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE. .PP Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à .MT debian-l10n-french@lists.debian.org .ME .