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'entête */ int cmsg_level; /* Protocole d'origine */ int cmsg_type; /* Type spécifique au protocole */ /* suivi de : unsigned char cmsg_data[]; */ };
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. Voir les pages relatives aux protocoles pour les types de messages de commande disponibles. La taille maximale d'un tampon de service par socket est paramétré avec le sysctl net.core.optmem_max. Voir socket(7).
CMSG_FIRSTHDR() renvoie un pointeur sur la première cmsghdr du tampon 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 tampon.
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 tampon de message de contrôle. Utilisez CMSG_FIRSTHDR() sur la structure 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'entê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 tampon. Pour plus d'informations sur msghdr, voir recvmsg(2).
Lorsque le tampon de message de contrôle est trop petit pour stocker tous les messages, l'attribut MSG_CTRUNC est activé dans le membre msg_flags de msghdr.
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.
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 passe une table de descripteurs de fichier 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;
Ce document est une traduction réalisée par Christophe Blaess <http://www.blaess.fr/christophe/> le 3 septembre 2000 et révisée le 17 juillet 2008.
L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 3 cmsg ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.
Dernière mise à jour : 17 juillet 2008