Provided by: manpages-fr_1.67.0-1_all bug

NOM

       CMSG_ALIGN,   CMSG_SPACE,   CMSG_NXTHDR,   CMSG_FIRSTHDR  -  Accès  aux
       informations de service.

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 length);
       size_t CMSG_SPACE(size_t length);
       size_t CMSG_LEN(size_t length);
       unsigned char *CMSG_DATA(struct cmsghdr *cmsg);

       struct cmsghdr {
         socklen_t     cmsg_len;   /* Nombre d’octets, y compris l’entête */
         int           cmsg_level; /* Protocole d’origine                 */
         int           cmsg_type;  /* Type spécifique au protocole        */
         /* suivi de :
         unsigned char cmsg_data[]; */
       };

DESCRIPTION

       Ces  macros  servent  à  créer  et  à  accéder aux messages de contrôle
       (informations de service - ancillary data) qui ne font  pas  partie  du
       trafic  normal  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 services peuvent servir à envoyer des champs
       d’en-tête supplémentaires tels que  les  options  IP.  Les  données  de
       services  sont  émises  avec  sendmsg(2) et reçues avec recvmsg(2).  Se
       reporter  à  leurs  pages  de  manuel  respectives  pour   avoir   plus
       d’informations.

       Une  information  de  service  est  une  séquence  de structures struct
       cmsghdr  avec  des  données  ajoutées.  Cette  séquence  ne  doit  être
       manipulée qu’au moyen des macros décrites dans cette page de manuel, et
       jamais directement. Voir les pages spécifiques des protocoles pour  les
       types  de  messages  de  commande  disponibles.   La taille maximale de
       buffer  de   service   par   socket   est   paramétré   avec   l’option
       net.core.optmem_max de sysctl(). Voir socket(7).

       CMSG_FIRSTHDR  renvoie un pointeur sur la première cmsghdr du buffer de
       données de service associé avec msghdr.

       CMSG_NXTHDR renvoie la cmsghdr suivante  après  la  cmsghdr  transmise.
       Elle renvoie NULL s’il n’y a plus assez de place dans le buffer.

       CMSG_ALIGN, renvoie la longueur transmise en argument additionnée de la
       taille nécessaire pour les  alignements.  Il  s’agit  d’une  expression
       constante.

       CMSG_SPACE renvoie le nombre d’octets occupés par un élément de service
       contenant la taille indiquée de données  transmises.  Il  s’agit  d’une
       expression constante.

       CMSG_DATA renvoie un pointeur sur les données d’une cmsghdr.

       CMSG_LEN  renvoie  la  valeur  à  stocker dans le membre cmsg_len d’une
       structure cmsghdr en tenant  compte  des  alignements.  Elle  prend  en
       argument   la   longueur  des  données.   Il  s’agit  d’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 buffer
       de message de contrôle.  Utilisez  CMSG_FIRSTHDR  sur  la  msghdr  pour
       obtenir  le premier message de contrôle, puis CMSG_NEXTHDR pour accéder
       aux suivants.  Dans chaque message de  contrôle,  initialisez  cmsg_len
       (avec  CMSG_LEN), les champs d’en-tête de l’autre cmsghdr, et la partie
       données  avec  CMSG_DATA.   Finallement,  il  faut  remplir  le  membre
       msg_controllen  de  la  structure  msghdr  avec  la somme de CMSG_SPACE
       appliqué à tous les messages de contrôle dans  le  buffer.   Pour  plus
       d’informations sur msghdr, voir recvmsg(2).

       Lorsque  le  buffer  de message de contrôle est trop court pour stocker
       tous les messages, l’attribut MSG_CTRUNC  est  activé  dans  le  membre
       msg_flags de msghdr.

EXEMPLE

       Ce code recherche l’option IP_TTL dans un buffer de messages de service
       reçus :

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

              /* Receive auxiliary data in msgh */
              for (cmsg = CMSG_FIRSTHDR(&msgh);
                   cmsg != NULL;
                   cmsg = CMSG_NXTHDR(&msgh,cmsg) {
                      if (cmsg->cmsg_level == SOL_IP
                        && cmsg->cmsg_type == IP_TTL) {
                              ttlptr = (int *) CMSG_DATA(cmsg);
                              received_ttl = *ttlptr;
                              break;
                      }
              }
              if (cmsg == NULL) {
                      /* Error: IP_TTL not enabled or small buffer
                       * or I/O error.
                       */
              }

       Ce code passe une table de descripteurs de fichiers  au  travers  d’une
       socket Unix en utilisant SCM_RIGHTS :

              struct msghdr msg = {0};
              struct cmsghdr *cmsg;
              int myfds[NUM_FD]; /* Contains the file descriptors to pass. */
              char buf[CMSG_SPACE(sizeof myfds)];  /* ancillary data buffer */
              int *fdptr;

              msg.msg_control = buf;
              msg.msg_controllen = sizeof buf;
              cmsg = CMSG_FIRSTHDR(&msg);
              cmsg->cmsg_level = SOL_SOCKET;
              cmsg->cmsg_type = SCM_RIGHTS;
              cmsg->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD);
              /* Initialize the payload: */
              fdptr = (int *)CMSG_DATA(cmsg);
              memcpy(fdptr, myfds, NUM_FD * sizeof(int));
              /* Sum of the length of all control messages in the buffer: */
              msg.msg_controllen = cmsg->cmsg_len;

NOTES

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

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

CONFORMITÉ

       Le  modèle  des  données de service est conforme à POSIX.1003.1g draft,
       4.4BSD-Lite,  l’API  IPv6  avancée  décrite  dans  la  RFC2292  et  les
       spécifications Single Unix v2.  CMSG_ALIGN est une extension Linux.

VOIR AUSSI

       sendmsg(2), recvmsg(2).

       RFC 2292

TRADUCTION

       Christophe Blaess, 2000-2003