Man page 3 : shm_open

shm_open, shm_unlink - Créer ou ouvrir et supprimer des objets de mémoire partagés POSIX

#include <sys/mman.h>
#include <sys/stat.h> /* Pour les constantes des modes */
#include <fcntl.h> /* Pour les constantes O_* */

int shm_open(const char *nom, int oflag, mode_t mode);

int shm_unlink(const char *nom);

Effectuez l'édition des liens avec l'option -lrt.

La fonction shm_open() crée et ouvre un nouvel objet de mémoire partagé POSIX, ou ouvre un objet existant. Il s'agit d'un descripteur utilisable par d'autres processus avec mmap(2) pour projeter la même région mémoire. La fonction shm_unlink() réalise l'opération complémentaire en supprimant l'objet créé précédemment par shm_open().

Le fonctionnement de shm_open() est analogue à celui de open(2). nom indique l'objet mémoire partagé à créer ou ouvrir. Pour un fonctionnement portable, un objet mémoire partagé doit être identifié par un nom au format /un_nom ; c'est-à-dire une chaîne terminée par un caractère nul d'au plus NAME_MAX (c'est-à-dire 255) caractère, commençant par une barre oblique (« / »), suivi d'un caractère ou plus, ces derniers n'étant pas des barres obliques.

oflag est un masque de bit associant l'une des deux constantes O_RDONLY ou O_RDWR et un ou plusieurs des attributs décrits ci-après.

• O_RDONLY
   Ouvrir l'objet en lecture seule. Un tel objet ne pourra être projeté en mémoire avec mmap(2) qu'avec l'accès (PROT_READ).
• O_RDWR
      Ouvrir l'objet en lecture et écriture.
• O_CREAT Créer l'objet de mémoire partagée s'il n'existe pas. L'utilisateur et le groupe propriétaires de l'objet proviennent des IDs effectifs du processus appelant, et les bits de permission sont définis en fonction des 9 bits de poids faible de mode, hormis les bits qui sont définis dans le masque de création du processus (consultez umask(2)) et qui sont effacés. Un jeu de constantes utilisables pour définir le mode est décrit dans open(2) (les définitions symboliques de ces constantes peuvent être obtenues en incluant <sys/stat.h>).
  
  Un nouvel objet de mémoire partagé a une taille initiale nulle - elle peut être définie avec ftruncate(2). Les octets d'un objet mémoire partagé nouvellement créé sont automatiquement initialisés à zéro.
• O_EXCL
      Si O_CREAT était précisé et si un objet de mémoire partagée avec le même nom existait déjà, renvoyer une erreur. La vérification et l'existence et la création éventuelle sont réalisées de manière atomique.
• O_TRUNC
      Si l'objet de mémoire partagée existait, tronquer sa taille à zéro.

Les définitions des valeurs de ces attributs peuvent être obtenues en incluant <fcntl.h>.

Si elle réussit, la fonction shm_open() renvoie un nouveau descripteur décrivant l'objet de mémoire partagée. Le descripteur est assuré d'être le plus petit numéro disponible dans la table des descripteurs du processus. L'attribut FD_CLOEXEC (consultez fcntl(2)) sera activé sur le descripteur de fichier. Le descripteur est utilisé normalement pour les appels ultérieurs à ftruncate(2) (pour un objet nouvellement créé) et mmap(2). Après un appel à mmap(2) le descripteur peut être fermé sans affecter la projection mémoire. Le fonctionnement de shm_unlink() est analogue à celui de unlink(2) : il supprime le nom d'un objet de mémoire partagée, et, une fois que tous les processus ont supprimé leur projection en mémoire, libère et détruit le contenu de la portion de mémoire. Après un appel réussi à shm_unlink(), les tentatives d'appeler shm_open() avec le même nom échoueront (sauf si O_CREAT est spécifié, auquel cas un nouvel objet distinc est créé).

S'il réussit, l'appel shm_open() renvoie un descripteur de fichier non négatif. S'il échoue, shm_open() renvoie -1. shm_unlink() renvoie 0 s'il réussit ou -1 en cas d'erreur.

Lors d'un échec, errno indique la cause de l'erreur. Les codes possibles dans errno sont les suivants :

• EACCES
      Interdiction d'utiliser shm_unlink() sur l'objet de mémoire partagée.
• EACCES
      shm_open() refusée pour le nom dans le mode indiqué, ou O_TRUNC a été réclamé et l'appelant n'a pas les permissions d'écriture sur l'objet.
• EEXIST
      O_CREAT et O_EXCL étaient réclamés dans shm_open() et un objet de mémoire partagée du même nom existait déjà.
• EINVAL
      L'argument nom de shm_open() était invalide.
• EMFILE
      Le processus a déjà ouvert le nombre maximal de fichiers.
• ENAMETOOLONG
      La longueur du nom dépasse PATH_MAX.
• ENFILE
      La limite du nombre total de fichiers ouverts sur le système a été atteinte.
• ENOENT
      Tentative d'ouvrir avec shm_open() un nom qui n'existe pas, sans attribut O_CREAT.
• ENOENT
      Tentative d'utiliser shm_unlink() sur un nom qui n'existe pas.

Ces fonctions sont fournies depuis la glibc 2.2.

POSIX.1-2001.

POSIX.1-2001 indique que le groupe propriétaire d'un objet 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 ne précise pas le comportement de la combinaison O_RDONLY et O_TRUNC. Sous Linux, la troncature aura lieu - cela n'est pas nécessairement le cas sous d'autres systèmes UNIX.

L'implémentation sous Linux 2.4 des objets de mémoire partagée POSIX utilise un système de fichiers dédiés, monté en principe sous /dev/shm.

close(2), fchmod(2), fchown(2), fcntl(2), fstat(2), ftruncate(2), mmap(2), open(2), umask(2), shm_overview(7)

Cette page fait partie de la publication 3.52 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/.

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). Nicolas François et l'équipe francophone de traduction de Debian (2006-2009).

Veuillez signaler toute erreur de traduction en écrivant à <>.

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