CMSG(3) Library Functions Manual CMSG(3) NOM CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR - Acceder aux informations de service BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include 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 creer et acceder aux messages de controle (aussi appele informations de service) qui ne font pas partie de la charge utile des sockets. Ces informations de controle peuvent inclure l'interface sur laquelle le paquet a ete recu, des champs d'en-tete rarement employes, des descriptions d'erreur approfondies, un ensemble de descripteurs de fichiers ou des identificateurs UNIX. Par exemple, les messages de controle peuvent etre utilises pour envoyer des champs d'en-tete supplementaires tels que des options IP. Les donnees de service sont emises en appelant sendmsg(2) et recues avec recvmsg(2). Reportez-vous a leurs pages de manuel respectives pour plus d'informations. Une information de service est une sequence de structures cmsghdr avec des donnees ajoutees. 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 etre definie a l'aide de /proc/sys/net/core/optmem_max. Consultez socket(7). La structure cmsghdr est definie comme suit : struct cmsghdr { size_t cmsg_len; /* Nombre d'octets de donnees, incluant l'en-tete (le type est socklen_t dans POSIX) */ int cmsg_level; /* Protocole d'origine */ int cmsg_type; /* Type specifique au protocole */ /* suivi par unsigned char cmsg_data[]; */ }; Plutot que d'acceder directement a la sequence de structures cmsghdr, il est imperatif d'utiliser les macros suivantes : CMSG_FIRSTHDR() renvoie un pointeur sur la premiere structure cmsghdr du tampon de donnees de service associe a la structure msghdr passee en parametre. 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 apres la structure cmsghdr passee en parametre. Elle renvoie NULL s'il n'y a plus assez de place dans le tampon. Lorsqu'on initialise un tampon qui contiendra une serie de structures cmsghdr (a envoyer par exemple en appelant sendmsg(2)), ce tampon doit etre initialise avec des zeros pour etre sur que CMSG_NXTHDR() fonctionnera correctement. CMSG_ALIGN(), avec comme argument une longueur, la renvoie en incluant l'alignement necessaire. C'est une expression constante. CMSG_SPACE() renvoie le nombre d'octets qu'occupe un element de service avec une charge utile de la longueur passee en parametre. C'est une expression constante. CMSG_DATA() renvoie un pointeur vers la partie donnees d'une structure cmsghdr. Il n'est pas certain que le pointeur renvoye soit correctement aligne pour acceder a des donnees de charge utile de type quelconque. Les applications ne doivent pas forcer son type a un type de pointeur correspondant a celui de la charge utile, mais doivent plutot utiliser memcpy(3) pour copier les donnees vers ou depuis un objet declare de maniere appropriee. CMSG_LEN() renvoie la valeur a stocker dans le membre cmsg_len de la structure cmsghdr, en tenant compte des alignements necessaires. Elle prend en parametre la longueur des donnees. C'est une expression constante. Pour creer des donnees de service, il faut tout d'abord initialiser le membre msg_controllen de la structure msghdr avec la longueur du tampon du message de controle. Utilisez CMSG_FIRSTHDR() sur la structure msghdr pour obtenir le premier message de controle, puis CMSG_NXTHDR() pour obtenir les suivants. Dans chaque message de controle, initialisez cmsg_len (avec CMSG_LEN()), les autres champs d'en-tete de cmsghdr et la partie des donnees avec CMSG_DATA(). Enfin, il faut definir 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 controle contenus dans le tampon..Pour plus d'informations sur la structure msghdr, consultez recvmsg(2). VERSIONS Pour des questions de portabilite, les donnees de service ne doivent etre manipulees qu'avec les macros decrites ici. Sous Linux, CMSG_LEN(), CMSG_DATA() et CMSG_ALIGN() sont des expressions constantes (si leur argument est une constante) ; elles peuvent donc etre utilisees pour declarer la taille de variables globales. Cela peut neanmoins ne pas etre portable. STANDARDS CMSG_FIRSTHDR() CMSG_NXTHDR() CMSG_DATA() POSIX.1-2008. CMSG_SPACE() CMSG_LEN() CMSG_ALIGN() Linux. HISTORIQUE Le modele des donnees de service est conforme a POSIX.1g draft, 4.4BSD-Lite, l'API IPv6 avancee decrite dans la RFC 2292 et SUSv2. CMSG_SPACE() et CMSG_LEN() seront incluses dans la prochaine version de POSIX (edition 8). EXEMPLES Ce code recherche l'option IP_TTL dans un tampon de service recu : struct msghdr msgh; struct cmsghdr *cmsg; int received_ttl; /* Recevoir des donnees 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; } } Le code ci-dessous passe un tableau de descripteurs de fichier au travers d'un socket de domaine UNIX a l'aide de SCM_RIGHTS : struct msghdr msg = { 0 }; struct cmsghdr *cmsg; int myfds[NUM_FD]; /* Contient les descripteurs de fichier a passer */ char iobuf[1]; struct iovec io = { .iov_base = iobuf, .iov_len = sizeof(iobuf) }; union { /* Tampon des donnees de service empaquete dans une union pour etre sur qu'il soit correctement aligne */ 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 a travers un socket de domaine UNIX, voir seccomp_unotify(2). VOIR AUSSI recvmsg(2), sendmsg(2) RFC 2292 TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot et Lucien Gentis Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 31 octobre 2023 CMSG(3)