Provided by:
manpages-fr_1.67.0-1_all 
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