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 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 sont utilisées pour 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 d'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 envoyées 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é en paramètre.
• 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.
• 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 sur la partie données d'une structure cmsghdr.
• 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).

Lorsque le tampon des messages de contrôle est trop petit pour stocker tous les messages, le drapeau MSG_CTRUNC est défini dans le membre msg_flags de la structure msghdr.

CONFORMITɶ

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

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;
/* 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) {


        ttlptr = (int *) CMSG_DATA(cmsg);


        received_ttl = *ttlptr;


        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 à transmettre */
int *fdptr;
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(int) * NUM_FD);
fdptr = (int *) CMSG_DATA(cmsg);    /* Initialise la charge utile */
memcpy(fdptr, myfds, NUM_FD * sizeof(int));

VOIR AUSSI¶

recvmsg(2), sendmsg(2)

RFC 2292

COLOPHON¶

Cette page fait partie de la publication 4.16 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies et la dernière version de cette page peuvent être trouvées à l'adresse https://www.kernel.org/doc/man-pages/.

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