.\" -*- coding: UTF-8 -*-
.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
.\"
.\" %%%LICENSE_START(VERBATIM_ONE_PARA)
.\" Permission is granted to distribute possibly modified copies
.\" of this page provided the header is included verbatim,
.\" and in case of nontrivial modification author and date
.\" of the modification is added to the header.
.\" %%%LICENSE_END
.\"
.\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH CMSG 3 "29 octobre 2022" "Pages du manuel de Linux 6.03" 
.SH NOM
CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- Accéder aux
informations de service
.SH BIBLIOTHÈQUE
Bibliothèque C standard (\fIlibc\fP, \fI\-lc\fP)
.SH SYNOPSIS
.nf
\fB#include <sys/socket.h>\fP
.PP
\fBstruct cmsghdr *CMSG_FIRSTHDR(struct msghdr *\fP\fImsgh\fP\fB);\fP
\fBstruct cmsghdr *CMSG_NXTHDR(struct msghdr *\fP\fImsgh\fP\fB,\fP
\fB                            struct cmsghdr *\fPcmsg\fB);\fP
\fBsize_t CMSG_ALIGN(size_t \fP\fIlongueur\fP\fB);\fP
\fBsize_t CMSG_SPACE(size_t \fP\fIlongueur\fP\fB);\fP
\fBsize_t CMSG_LEN(size_t \fP\fIlongueur\fP\fB);\fP
\fBunsigned char *CMSG_DATA(struct cmsghdr *\fP\fIcmsg\fP\fB);\fP
.fi
.SH 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 rarement 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 service sont émises en appelant \fBsendmsg\fP(2) et
reçues avec \fBrecvmsg\fP(2). Reportez\-vous à leurs pages de manuel respectives
pour plus d'informations.
.PP
Une information de service est une séquence de structures \fIcmsghdr\fP 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
\fI/proc/sys/net/core/optmem_max\fP. Consultez \fBsocket\fP(7).
.PP
La structure \fIcmsghdr\fP est définie comme suit\ :
.PP
.in +4n
.EX
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[]; */
};
.EE
.in
.PP
Plutôt que d'accéder directement à la séquence de structures \fIcmsghdr\fP, il
est impératif d'utiliser les macros suivantes\ :
.TP 
\fBCMSG_FIRSTHDR\fP()
renvoie un pointeur sur la première structure \fIcmsghdr\fP du tampon de
données de service associé à la structure \fImsghdr\fP passée en
paramètre. Elle renvoie NULL s'il n'y a pas assez de place pour une
structure \fIcmsghdr\fP dans le tampon.
.TP 
\fBCMSG_NXTHDR\fP()
renvoie la prochaine structure \fIcmsghdr\fP valable après la structure
\fIcmsghdr\fP passée en paramètre. Elle renvoie NULL s'il n'y a plus assez de
place dans le tampon.
.IP
Lorsqu'on initialise un tampon qui contiendra une série de structures
\fIcmsghdr\fP (à envoyer par exemple en appelant \fBsendmsg\fP(2)), ce tampon doit
être initialisé avec des zéros pour être sûr que \fBCMSG_NXTHDR\fP()
fonctionnera correctement.
.TP 
\fBCMSG_ALIGN\fP(),
avec comme argument une longueur, la renvoie en incluant l'alignement
nécessaire. C'est une expression constante.
.TP 
\fBCMSG_SPACE\fP()
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.
.TP 
\fBCMSG_DATA\fP()
 renvoie un pointeur vers la partie données d'une structure \fIcmsghdr\fP. Il
n'est pas certain que le pointeur renvoyé soit correctement 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 \fBmemcpy\fP(3) pour copier
les données vers ou depuis un objet déclaré de manière appropriée.
.TP 
\fBCMSG_LEN\fP()
renvoie la valeur à stocker dans le membre \fIcmsg_len\fP de la structure
\fIcmsghdr\fP, en tenant compte des alignements nécessaires. Elle prend en
paramètre la longueur des données. C'est une expression constante.
.PP
Pour créer des données de service, il faut tout d'abord initialiser le
membre \fImsg_controllen\fP de la structure \fImsghdr\fP avec la longueur du
tampon du message de contrôle. Utilisez \fBCMSG_FIRSTHDR\fP() sur la structure
\fImsghdr\fP pour obtenir le premier message de contrôle, puis \fBCMSG_NXTHDR\fP()
pour obtenir les suivants. Dans chaque message de contrôle, initialisez
\fIcmsg_len\fP (avec \fBCMSG_LEN\fP()), les autres champs d'en\-tête de \fIcmsghdr\fP
et la partie des données avec \fBCMSG_DATA\fP(). Enfin, il faut définir le
membre \fImsg_controllen\fP de la structure \fImsghdr\fP avec la somme des valeurs
de retour de \fBCMSG_SPACE\fP() pour la longueur de tous les messages de
contrôle contenus dans le tampon..Pour plus d'informations sur la structure
\fImsghdr\fP, consultez \fBrecvmsg\fP(2).
.SH STANDARDS
.\" https://www.austingroupbugs.net/view.php?id=978#c3242
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. \fBCMSG_FIRSTHDR\fP(),
\fBCMSG_NXTHDR\fP() et \fBCMSG_DATA\fP() sont spécifiées dans
POSIX.1\-2008. \fBCMSG_SPACE\fP() et \fBCMSG_LEN\fP() seront incluses dans la
prochaine version de POSIX (édition 8).
.PP
\fBCMSG_ALIGN\fP() est une extension Linux.
.SH NOTES
Pour des questions de portabilité, les données de service ne doivent être
manipulées qu'avec les macros décrites ici. \fBCMSG_ALIGN\fP() est une
extension Linux et ne doit pas être utilisée dans un programme portable.
.PP
Sous Linux, \fBCMSG_LEN\fP(), \fBCMSG_DATA\fP() et \fBCMSG_ALIGN\fP() 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.
.SH EXEMPLES
Ce code recherche l'option \fBIP_TTL\fP dans un tampon de service reçu\ :
.PP
.in +4n
.EX
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 */
}
.EE
.in
.PP
Le code ci\-dessous passe un tableau de descripteurs de fichier au travers
d'un socket de domaine UNIX à l'aide de \fBSCM_RIGHTS\fP\ :
.PP
.in +4n
.EX
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));
.EE
.in
.PP
Pour un exemple de code complet qui montre la transmission de descripteurs
de fichier à travers un socket de domaine UNIX, voir \fBseccomp_unotify\fP(2).
.SH "VOIR AUSSI"
\fBrecvmsg\fP(2), \fBsendmsg\fP(2)
.PP
RFC\ 2292
.PP
.SH 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>
.
.PP
Cette traduction est une documentation libre ; veuillez vous reporter à la
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License version 3
.UE
concernant les conditions de copie et 
de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
.PP
Si vous découvrez un bogue dans la traduction de cette page de manuel, 
veuillez envoyer un message à
.MT debian-l10n-french@lists.debian.org
.ME .