CMSG(3) Library Functions Manual CMSG(3)
NOM
CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR - Accéder aux infor-
mations de service
BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)
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 permettent de 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 ra-
rement 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 ser-
vice sont émises en appelant sendmsg(2) et reçues avec recvmsg(2). Re-
portez-vous à leurs pages de manuel respectives pour plus d'informa-
tions.
Une information de service est une séquence de structures cmsghdr avec
des données ajoutées. Consultez les pages de manuel relatives aux pro-
tocoles 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ée en
paramètre. 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 après la struc-
ture cmsghdr passée en paramètre. Elle renvoie NULL s'il n'y a
plus assez de place dans le tampon.
Lorsqu'on initialise un tampon qui contiendra une série de
structures cmsghdr (à envoyer par exemple en appelant
sendmsg(2)), ce tampon doit être initialisé avec des zéros pour
être sûr que CMSG_NXTHDR() fonctionnera correctement.
CMSG_ALIGN(),
avec comme argument une longueur, la renvoie en incluant l'ali-
gnement 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 vers la partie données d'une structure cm-
sghdr. Il n'est pas certain que le pointeur renvoyé soit correc-
tement aligné pour accéder à des données de charge utile de type
quelconque. Les applications ne doivent pas forcer son type à un
type de pointeur correspondant à celui de la charge utile, mais
doivent plutôt utiliser memcpy(3) pour copier les données vers
ou depuis un objet déclaré de manière appropriée.
CMSG_LEN()
renvoie la valeur à stocker dans le membre cmsg_len de la struc-
ture 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).
STANDARDS
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_FIRSTHDR(), CMSG_NXTHDR() et CMSG_DATA() sont spécifiées dans PO-
SIX.1-2008. CMSG_SPACE() et CMSG_LEN() seront incluses dans la pro-
chaine version de POSIX (édition 8).
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 por-
table.
Sous Linux, CMSG_LEN(), CMSG_DATA() et CMSG_ALIGN() sont des expres-
sions 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.
EXEMPLES
Ce code recherche l'option IP_TTL dans un tampon de service reçu :
struct msghdr msgh;
struct cmsghdr *cmsg;
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) {
memcpy(&receive_ttl, CMSG_DATA(cmsg), sizeof(received_ttl));
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 tra-
vers 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 à passer */
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(myfds));
memcpy(CMSG_DATA(cmsg), myfds, sizeof(myfds));
Pour un exemple de code complet qui montre la transmission de descrip-
teurs de fichier à travers un socket de domaine UNIX, voir seccomp_uno-
tify(2).
VOIR AUSSI
recvmsg(2), sendmsg(2)
RFC 2292
TRADUCTION
La traduction française de cette page de manuel a été créée par Chris-
tophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <ste-
phan.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.cou-
lon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux
<thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centra-
liens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <si-
mon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@de-
bian.org>, David Prévot <david@tilapin.org> et Lucien Gentis <lu-
cien.gentis@waika9.com>
Cette traduction est une documentation libre ; veuillez vous reporter à
la GNU General Public License version 3
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ 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⟩.
Pages du manuel de Linux 6.03 29 octobre 2022 CMSG(3)
Generated by dwww version 1.15 on Sat Jun 29 00:26:27 CEST 2024.