Loading

NOM

       CMSG_ALIGN,   CMSG_SPACE,  CMSG_NXTHDR,  CMSG_FIRSTHDR  -  Accéder  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 de données, incluant l’en-tête */
           int       cmsg_level;  /* Protocole d’origine */
           int       cmsg_type;   /* Type spécifique au protocole */
           /* suivi par unsigned char cmsg_data[]; */
       };

       Ces  macros  sont  utilisées  pour  créer  et  accéder  aux messages de
       contrôle (aussi appelé informations de service) 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 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  avec  sendmsg(2)  et  reçues  avec
       recvmsg(2). Reportez-vous à leur page de manuel  respective  pour  plus
       d’informations.

       Une  information de service est une séquence de structures 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.
       Voyez les pages relatives  aux  protocoles  des  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.
       Voyez socket(7).

       CMSG_FIRSTHDR()  renvoie  un pointeur sur la première cmsghdr du tampon
       de données de service associé au msghdr passé.

       CMSG_NXTHDR() renvoie le prochain  cmsghdr  valable  suivant  après  le
       cmsghdr transmis. Elle renvoie NULL s’il n’y a plus assez de place dans
       le tampon.

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

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

       CMSG_DATA()  renvoie  un  pointeur  sur  une  partie  des  données d’un
       cmsghdr.

       CMSG_LEN() renvoie la valeur à stocker dans le membre  cmsg_len  de  la
       structure  cmsghdr,  en  tenant  compte  des alignements. 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
       message de contrôle. Utilisez CMSG_FIRSTHDR() sur la  structure  msghdr
       pour  obtenir  le premier message de contrôle, puis CMSG_NEXTHDR() 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 de données avec CMSG_DATA(). Enfin, il faut définir le membre
       msg_controllen  de  la  structure  msghdr  avec  la  somme  de tous les
       messages de contrôle dans le tampon renvoyé par CMSG_SPACE().Pour  plus
       d’informations sur msghdr, voyez recvmsg(2).

       Lorsque  le  tampon  de message de contrôle est trop petit pour stocker
       tous les messages, le drapeau MSG_CTRUNC du membre msg_flags de  msghdr
       est activé.

CONFORMITÉ

       Le  modèle  des  données  de  service  est  conforme  à POSIX.1g draft,
       BSD4.4-Lite, « IPv6 advanced API » décrite dans la RFC 2292  et  SUSv2.
       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) ; on peut
       donc les utiliser pour déclarer la taille de variables  globales.  Cela
       peut néanmoins ne pas être portable.

EXEMPLE

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

           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 == IPPROTO_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,  ci-dessous,  passe  une  table de descripteurs de fichier au
       travers d’une socket Unix avec 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;

VOIR AUSSI

       recvmsg(2), sendmsg(2)

       RFC 2292

COLOPHON

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

TRADUCTION

       Cette  page  de  manuel  a  été  traduite et mise à jour par Christophe
       Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis  par
       Alain  Portal  <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
       disposition sur http://manpagesfr.free.fr/.

       Les mises à jour et corrections de la version présente dans Debian sont
       directement gérées par Florentin Duneau <fduneau@gmail.com> et l’équipe
       francophone de traduction de Debian.

       Veuillez  signaler  toute  erreur   de   traduction   en   écrivant   à
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

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