Provided by: manpages-fr-dev_4.19.0-7_all bug

NOM

       CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR - Accéder aux informations de service

BIBLIOTHÈQUE

       Bibliothèque C standard (libc, -lc)

SYNOPSIS

       #include <sys/socket.h>

       struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *msgh);
       struct cmsghdr *CMSG_NXTHDR(struct msghdr *msgh,
                                   struct cmsghdr *cmsg);
       size_t CMSG_ALIGN(size_t longueur);
       size_t CMSG_SPACE(size_t longueur);
       size_t CMSG_LEN(size_t longueur);
       unsigned char *CMSG_DATA(struct cmsghdr *cmsg);

DESCRIPTION

       Ces  macros  permettent  de  créer  et  accéder  aux  messages  de  contrôle (aussi appelé
       informations de service) qui ne font pas partie  de  la  charge  utile  des  sockets.  Ces
       informations  de  contrôle  peuvent inclure l'interface sur laquelle le paquet a été reçu,
       des champs  d'en-tête  rarement  employés,  des  descriptions  d'erreur  approfondies,  un
       ensemble  de  descripteurs  de  fichiers  ou  des  identificateurs  UNIX. Par exemple, les
       messages  de  contrôle  peuvent  être  utilisés  pour   envoyer   des   champs   d'en-tête
       supplémentaires  tels  que  des options IP. Les données de service sont émises en appelant
       sendmsg(2) et reçues avec recvmsg(2). Reportez-vous à leurs pages  de  manuel  respectives
       pour plus d'informations.

       Une  information  de  service  est  une  séquence  de  structures cmsghdr avec des données
       ajoutées. Consultez les pages de manuel relatives aux protocoles pour les types de message
       de  commande  disponibles.  La taille maximale d'un tampon de service par socket peut être
       définie à l'aide de /proc/sys/net/core/optmem_max. Consultez socket(7).

       La structure cmsghdr est définie comme suit :

           struct cmsghdr {
               size_t cmsg_len;    /* Nombre d'octets de données, incluant l'en-tête
                                      (le type est socklen_t dans POSIX) */
               int    cmsg_level;  /* Protocole d'origine */
               int    cmsg_type;   /* Type spécifique au protocole */
           /* suivi par
              unsigned char cmsg_data[]; */
           };

       Plutôt que d'accéder directement à la séquence de structures  cmsghdr,  il  est  impératif
       d'utiliser les macros suivantes :

       CMSG_FIRSTHDR()
              renvoie  un  pointeur  sur  la  première  structure cmsghdr du tampon de données de
              service associé à la structure msghdr passée en paramètre. Elle renvoie  NULL  s'il
              n'y a pas assez de place pour une structure cmsghdr dans le tampon.

       CMSG_NXTHDR()
              renvoie la prochaine structure cmsghdr valable après la structure cmsghdr passée en
              paramètre. Elle renvoie NULL s'il n'y a plus assez de place dans le tampon.

              Lorsqu'on initialise un tampon qui contiendra une série de  structures  cmsghdr  (à
              envoyer  par  exemple  en appelant sendmsg(2)), ce tampon doit être initialisé avec
              des zéros pour être sûr que CMSG_NXTHDR() fonctionnera correctement.

       CMSG_ALIGN(),
              avec comme argument une longueur, la renvoie en incluant  l'alignement  nécessaire.
              C'est une expression constante.

       CMSG_SPACE()
              renvoie le nombre d'octets qu'occupe un élément de service avec une charge utile de
              la longueur passée en paramètre. C'est une expression constante.

       CMSG_DATA()
               renvoie un pointeur vers la partie données d'une structure cmsghdr. Il  n'est  pas
              certain que le pointeur renvoyé soit correctement aligné pour accéder à des données
              de charge utile de type quelconque. Les applications ne doivent pas forcer son type
              à un type de pointeur correspondant à celui de la charge utile, mais doivent plutôt
              utiliser memcpy(3) pour copier les données vers  ou  depuis  un  objet  déclaré  de
              manière appropriée.

       CMSG_LEN()
              renvoie  la  valeur  à  stocker dans le membre cmsg_len de la structure cmsghdr, en
              tenant compte des alignements nécessaires. Elle prend en paramètre la longueur  des
              données. C'est une expression constante.

       Pour   créer  des  données  de  service,  il  faut  tout  d'abord  initialiser  le  membre
       msg_controllen de la structure msghdr avec la longueur du tampon du message  de  contrôle.
       Utilisez  CMSG_FIRSTHDR()  sur  la  structure  msghdr  pour  obtenir le premier message de
       contrôle, puis CMSG_NXTHDR() pour obtenir les suivants. Dans chaque message  de  contrôle,
       initialisez  cmsg_len  (avec  CMSG_LEN()),  les  autres  champs d'en-tête de cmsghdr et la
       partie des données avec CMSG_DATA(). Enfin, il faut définir le membre msg_controllen de la
       structure  msghdr  avec la somme des valeurs de retour de CMSG_SPACE() pour la longueur de
       tous les messages de contrôle contenus dans le tampon..Pour  plus  d'informations  sur  la
       structure msghdr, consultez recvmsg(2).

STANDARDS

       Le  modèle  des  données de service est conforme à POSIX.1g draft, 4.4BSD-Lite, l'API IPv6
       avancée décrite dans la RFC 2292 et SUSv2. CMSG_FIRSTHDR(), CMSG_NXTHDR()  et  CMSG_DATA()
       sont  spécifiées  dans  POSIX.1-2008.  CMSG_SPACE()  et CMSG_LEN() seront incluses dans la
       prochaine version de POSIX (édition 8).

       CMSG_ALIGN() est une extension Linux.

NOTES

       Pour des questions de portabilité, les données  de  service  ne  doivent  être  manipulées
       qu'avec  les macros décrites ici. CMSG_ALIGN() est une extension Linux et ne doit pas être
       utilisée dans un programme portable.

       Sous Linux, CMSG_LEN(), CMSG_DATA() et CMSG_ALIGN() sont des  expressions  constantes  (si
       leur  argument  est  une  constante) ;  elles peuvent donc être utilisées pour déclarer la
       taille de variables globales. Cela peut néanmoins ne pas être portable.

EXEMPLES

       Ce code recherche l'option IP_TTL dans un tampon de service reçu :

           struct msghdr msgh;
           struct cmsghdr *cmsg;
           int received_ttl;

           /* Recevoir des données de service dans msgh */

           for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;
                   cmsg = CMSG_NXTHDR(&msgh, cmsg)) {
               if (cmsg->cmsg_level == IPPROTO_IP
                       && cmsg->cmsg_type == IP_TTL) {
                   memcpy(&receive_ttl, CMSG_DATA(cmsg), sizeof(received_ttl));
                   break;
               }
           }

           if (cmsg == NULL) {
               /* Erreur : IP_TTL non activée, tampon trop petit ou erreur d'entrée/sortie */
           }

       Le code ci-dessous passe un tableau de descripteurs de fichier au travers d'un  socket  de
       domaine UNIX à l'aide de SCM_RIGHTS :

           struct msghdr msg = { 0 };
           struct cmsghdr *cmsg;
           int myfds[NUM_FD];  /* Contient les descripteurs de fichier à passer */
           char iobuf[1];
           struct iovec io = {
               .iov_base = iobuf,
               .iov_len = sizeof(iobuf)
           };
           union {         /* Tampon des données de service empaqueté dans une union
                              pour être sûr qu'il soit correctement aligné */
               char buf[CMSG_SPACE(sizeof(myfds))];
               struct cmsghdr align;
           } u;

           msg.msg_iov = &io;
           msg.msg_iovlen = 1;
           msg.msg_control = u.buf;
           msg.msg_controllen = sizeof(u.buf);
           cmsg = CMSG_FIRSTHDR(&msg);
           cmsg->cmsg_level = SOL_SOCKET;
           cmsg->cmsg_type = SCM_RIGHTS;
           cmsg->cmsg_len = CMSG_LEN(sizeof(myfds));
           memcpy(CMSG_DATA(cmsg), myfds, sizeof(myfds));

       Pour  un  exemple  de code complet qui montre la transmission de descripteurs de fichier à
       travers un socket de domaine UNIX, voir seccomp_unotify(2).

VOIR AUSSI

       recvmsg(2), sendmsg(2)

       RFC 2292

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>,   David   Prévot   <david@tilapin.org>  et  Lucien  Gentis
       <lucien.gentis@waika9.com>

       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⟩.