.\" -*- coding: UTF-8 -*-
.\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" SPDX-License-Identifier: BSD-4-Clause-UC
.\"
.\" $Id: recv.2,v 1.3 1999/05/13 11:33:38 freitag Exp $
.\"
.\" Modified Sat Jul 24 00:22:20 1993 by Rik Faith <faith@cs.unc.edu>
.\" Modified Tue Oct 22 17:45:19 1996 by Eric S. Raymond <esr@thyrsus.com>
.\" Modified 1998,1999 by Andi Kleen
.\" 2001-06-19 corrected SO_EE_OFFENDER, bug report by James Hawtin
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH recv 2 "3 décembre 2022" "Pages du manuel de Linux 6.03"
.SH NOM
recv, recvfrom, recvmsg \- Recevoir un message d'un socket
.SH BIBLIOTHÈQUE
Bibliothèque C standard (\fIlibc\fP, \fI\-lc\fP)
.SH SYNOPSIS
.nf
\fB#include <sys/socket.h>\fP
.PP
\fBssize_t recv(int \fP\fIsockfd\fP\fB, void \fP\fIbuf\fP\fB[.\fP\fIlen\fP\fB], size_t \fP\fIlen\fP\fB,\fP
\fB int \fP\fIflags\fP\fB);\fP
\fBssize_t recvfrom(int \fP\fIsockfd\fP\fB, void \fP\fIbuf\fP\fB[restrict .\fP\fIlen\fP\fB], size_t \fP\fIlen\fP\fB,\fP
\fB int \fP\fIflags\fP\fB,\fP
\fB struct sockaddr *_Nullable restrict \fP\fIsrc_addr\fP\fB,\fP
\fB socklen_t *_Nullable restrict \fP\fIaddrlen\fP\fB);\fP
\fBssize_t recvmsg(int \fP\fIsockfd\fP\fB, struct msghdr *\fP\fImsg\fP\fB, int \fP\fIflags\fP\fB);\fP
.fi
.SH DESCRIPTION
Les appels système \fBrecv\fP(), \fBrecvfrom\fP() et \fBrecvmsg\fP() sont utilisés
pour recevoir des messages depuis un socket, et peuvent servir sur un socket
orienté connexion ou non. Cette page décrit dans un premier temps les
fonctionnalités communes de ces trois appels système, puis précise ensuite
ce qui les différencie.
.PP
La seule différence entre \fBrecv\fP() et \fBread\fP(2) est la présence de
\fIflags\fP. Si l’argument \fIflags\fP est absent, \fBrecv\fP() est généralement
équivalent à \fBread\fP(2) (mais voir les NOTES). De plus, l'appel suivant
.PP
.in +4n
.EX
recv(sockfd, buf, len, flags);
.EE
.in
.PP
est équivalent à\ :
.PP
.in +4n
.EX
recvfrom(sockfd, buf, len, flags, NULL, NULL);
.EE
.in
.PP
Ces trois appels renvoient la longueur du message s'ils réussissent. Si un
message est trop long pour tenir dans le tampon, les octets supplémentaires
peuvent être abandonnés suivant le type de socket utilisé.
.PP
Si aucun message n'est disponible sur le socket, les appels à réception se
mettent en attente, à moins que le socket soit non bloquant (voir
\fBfcntl\fP(2)), auquel cas la valeur \fB\-1\fP est renvoyée et \fIerrno\fP est
positionnée à \fBEAGAIN\fP ou \fBEWOULDBLOCK\fP. Les appels à réception renvoient
normalement les données disponibles, jusqu’au montant demandé, sans attendre
d'avoir reçu le nombre exact réclamé.
.PP
Une application peut avoir recours à \fBselect\fP(2), \fBpoll\fP(2), ou
\fBepoll\fP(7) pour savoir si des données supplémentaires arrivent dans le
socket.
.SS "Le paramètre des attributs"
L'argument \fIflags\fP est constitué à partir d'un \fIOU\fP binaire entre une ou
plusieurs des valeurs suivantes\ :
.TP
\fBMSG_CMSG_CLOEXEC\fP (\fBrecvmsg\fP() uniquement\ ; depuis Linux 2.6.23)
Positionner l'attribut «\ close\-on\-exec\ » pour le descripteur de fichier reçu
à l’aide d’un descripteur de fichier de domaine UNIX en utilisant
l'opération \fBSCM_RIGHTS\fP (décrite dans \fBunix\fP(7)). Cet attribut est utile
pour les mêmes raisons que l'attribut \fBO_CLOEXEC\fP de \fBopen\fP(2).
.TP
\fBMSG_DONTWAIT\fP (depuis Linux 2.2)
Activer l'opération non bloquante\ ; si elle bloque, l'appel échoue avec
l'erreur \fBEAGAIN\fP ou \fBEWOULDBLOCK\fP. Cela fournit un comportement identique
à la définition de l'attribut \fBO_NONBLOCK\fP (à l'aide de l'opération
\fBF_SETFL\fP de \fBfcntl\fP(2)), sauf que \fBMSG_DONTWAIT\fP est une option pour
chaque appel tandis que \fBO_NONBLOCK\fP est un paramètre sur la description du
fichier ouvert (voir \fBopen\fP(2)), qui touchera tous les threads du processus
appelant ainsi que d'autres processus détenant des descripteurs de fichier
se rapportant à la même description de fichier ouvert.
.TP
\fBMSG_ERRQUEUE\fP (depuis Linux 2.2)
Cet attribut demande que les erreurs soient reçues depuis la file d'erreur
du socket. Les erreurs sont transmises dans un message annexe dont le type
dépend du protocole (\fBIP_RECVERR\fP pour IPv4). Il faut alors fournir un
tampon de taille suffisante. Consultez \fBcmsg\fP(3) et \fBip\fP(7) pour plus de
détails. Le contenu du paquet original qui a causé l'erreur est passé en
tant que données normales dans \fImsg_iovec\fP. L'adresse de destination
originale du datagramme ayant causé l'erreur est fournie dans \fImsg_name\fP.
.IP
L'erreur est contenue dans une structure \fIsock_extended_err\fP\ :
.IP
.in +4n
.EX
#define SO_EE_ORIGIN_NONE 0
#define SO_EE_ORIGIN_LOCAL 1
#define SO_EE_ORIGIN_ICMP 2
#define SO_EE_ORIGIN_ICMP6 3
struct sock_extended_err
{
uint32_t ee_errno; /* numéro d'erreur */
uint8_t ee_origin; /* origine de l'erreur */
uint8_t ee_type; /* type */
uint8_t ee_code; /* code */
uint8_t ee_pad; /* remplissage */
uint32_t ee_info; /* données supplémentaires */
uint32_t ee_data; /* autres données */
/* Des données supplémentaires peuvent suivre */
};
struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);
.EE
.in
.IP
\fIee_errno\fP contient le code \fIerrno\fP de l'erreur en file
d’attente. \fIee_origin\fP est le code d'origine d’où l’erreur provient. Les
autres champs sont spécifiques au protocole. La macro \fBSO_EE_OFFENDER\fP
renvoie un pointeur sur l'adresse de l'objet réseau ayant déclenché
l'erreur, en donnant un pointeur sur le message annexe. Si cette adresse
n'est pas connue, le membre \fIsa_family\fP de la structure \fIsockaddr\fP
contient \fBAF_UNSPEC\fP et les autres champs de la structure \fIsockaddr\fP sont
indéfinis. Le contenu du paquet ayant déclenché l'erreur est transmis en
données normales.
.IP
Pour les erreurs locales, aucune adresse n'est passée (cela peut être
vérifié dans le membre \fIcmsg_len\fP de \fIcmsghdr\fP). À la réception d'une
erreur, \fBMSG_ERRQUEUE\fP est placé dans \fImsghdr\fP. Après réception d'une
erreur, l'erreur en attente sur le socket est régénérée en fonction de la
prochaine erreur dans la file et sera transmise lors de l'opération suivante
sur le socket.
.TP
\fBMSG_OOB\fP
Cette option demande la réception de données hors\-bande qui ne seraient pas
reçues dans le flux normal de données. Certains protocoles placent ces
données hors\-bande en tête de la file normale, et cette option n'a pas lieu
d'être dans ce cas.
.TP
\fBMSG_PEEK\fP
Cette option fait que l’opération de réception renvoie les données du début
de la queue de réception sans les enlever de cette file. Ainsi un appel à
réception ultérieur renverra à nouveau les mêmes données.
.TP
\fBMSG_TRUNC\fP (depuis Linux 2.2)
.\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f
Pour les sockets bruts (\fBAF_PACKET\fP), de datagrammes Internet (depuis
Linux\ 2.4.27/2.6.8), netlink (depuis Linux\ 2.6.22) et de datagrammes UNIX
(depuis Linux\ 3.4)\ : renvoyer la taille réelle du paquet ou datagramme, même
quand il est plus grand que le tampon fourni.
.IP
Pour une utilisation avec des sockets de flux Internet, consultez \fBtcp\fP(7).
.TP
\fBMSG_WAITALL\fP (depuis Linux 2.2)
.\"
Ce drapeau demande que l'opération de lecture soit bloquée jusqu'à ce que la
requête complète soit satisfaite. Toutefois, la lecture peut renvoyer quand
même moins de données que prévu si un signal est reçu, si une erreur ou une
déconnexion se produisent ou si les données suivantes à recevoir sont d'un
type différent de celles renvoyées. Ce drapeau n'a aucun effet sur les
sockets de datagramme.
.SS recvfrom()
\fBrecvfrom\fP() enregistre le message reçu dans le tampon \fIbuf\fP. Le processus
appelant doit préciser la taille de ce tampon dans \fIlen\fP.
.PP
.\" (Note: for datagram sockets in both the UNIX and Internet domains,
.\" .I src_addr
.\" is filled in.
.\" .I src_addr
.\" is also filled in for stream sockets in the UNIX domain, but is not
.\" filled in for stream sockets in the Internet domain.)
.\" [The above notes on AF_UNIX and AF_INET sockets apply as at
.\" Kernel 2.4.18. (MTK, 22 Jul 02)]
Si \fIsrc_addr\fP n'est pas NULL, et si le protocole sous\-jacent fournit
l'adresse de la source, celle\-ci y est insérée dans le tampon désigné par
\fIsrc_addr\fP. Dans ce cas, \fIaddrlen\fP est un paramètre valeur\-résultat. Avant
l'appel, il doit être initialisé à la valeur de la taille du tampon associé
à \fIsrc_addr\fP. En retour, \fIaddrlen\fP est mis à jour avec la valeur réelle de
l'adresse source. Cette adresse est tronquée si le tampon fourni n'a pas une
taille suffisante\ ; dans ce cas \fIaddrlen\fP renvoie un valeur supérieure à
celle fournie lors de l'appel.
.PP
.\"
Si le processus appelant n'est pas intéressé par l'adresse de la source,
\fIsrc_addr\fP et \fIaddrlen\fP doivent avoir la valeur NULL.
.SS recv()
L'appel \fBrecv\fP() est normalement utilisé sur un socket \fIconnecté\fP (voir
\fBconnect\fP(2)). Il est équivalent à l'appel\ :
.PP
.in +4n
.EX
recvfrom(fd, buf, len, flags, NULL, 0);
.EE
.in
.\"
.SS recvmsg()
L'appel \fBrecvmsg\fP() utilise une structure \fImsghdr\fP pour minimiser le
nombre de paramètres à fournir directement. Cette structure est définie dans
\fI<sys/socket.h>\fP comme ceci\ :
.PP
.in +4n
.EX
struct msghdr {
void *msg_name; /* Adresse optionnelle */
socklen_t msg_namelen; /* Taille de l'adresse */
struct iovec *msg_iov; /* Tableau scatter/gather */
size_t msg_iovlen; /* Nb. d’éléments dans msg_iov */
void *msg_control; /* Données annexes, voir ci\(hydessous */
size_t msg_controllen; /* Taille du tampon de données annexe */
int msg_flags; /* Attributs du message reçu */
};
.EE
.in
.PP
Le champ \fImsg_name\fP pointe vers un tampon alloué par l'appelant et qui est
utilisé pour renvoyer l'adresse source lorsque le socket n'est pas
connecté. L'appelant doit initialiser \fImsg_namelen\fP avec la taille de ce
tampon avant l'appel\ ; si l'appel s'exécute avec succès, \fImsg_name\fP prend
pour valeur la longueur de l'adresse renvoyée. Si l'application n'a pas
besoin de connaître l'adresse source, on peut affecter la valeur NULL à
\fImsg_name\fP.
.PP
Les champs \fImsg_iov\fP et \fImsg_iovlen\fP décrivent les emplacements de
dispersion\-regroupement (scatter\-gather) tels qu'expliqués dans \fBreadv\fP(2).
.PP
Le champ \fImsg_control\fP, de longueur \fImsg_controllen\fP, pointe sur un tampon
utilisé pour les autres messages du protocole relatifs au contrôle, ou à
d'autres données annexes. Lorsqu'on invoque \fBrecvmsg\fP, \fImsg_controllen\fP
doit contenir la longueur du tampon disponible dans \fImsg_control\fP\ ; lors
du retour d’un appel réussi,il contiendra la longueur de la séquence du
message de contrôle.
.PP
Les messages ont la forme
.PP
.in +4n
.EX
struct cmsghdr {
size_t cmsg_len; /* nombre d'octets de données, y compris l'en\-tête
(de type socklen_t dans POSIX) */
int cmsg_level; /* protocole d'origine */
int cmsg_type; /* type dépendant du protocole */
/* suivi de
unsigned char cmsg_data[]; */
};
.EE
.in
.PP
Les données annexes ne doivent être manipulées qu'avec les macros de
\fBcmsg\fP(3).
.PP
À titre d'exemple, Linux utilise ce mécanisme de données annexes pour
transmettre des erreurs étendues, des options IP ou des descripteurs de
fichier sur des sockets de domaine UNIX. Pour plus d'informations sur
l'utilisation de ce mécanisme sur divers domaines de socket, voir \fBunix\fP(7)
et \fBip\fP(7).
.PP
Le champ \fImsg_flags\fP du \fImsghdr\fP est rempli au retour de \fBrecvmsg\fP(). Il
peut contenir plusieurs attributs\ :
.TP
\fBMSG_EOR\fP
indique une fin d'enregistrement, les données reçues terminent un
enregistrement (utilisé généralement avec les sockets du type
\fBSOCK_SEQPACKET\fP).
.TP
\fBMSG_TRUNC\fP
indique que la portion finale du datagramme a été abandonnée car le
datagramme était trop long pour le tampon fourni.
.TP
\fBMSG_CTRUNC\fP
indique que des données de contrôle ont été abandonnées à cause d'un manque
de place dans le tampon de données annexes.
.TP
\fBMSG_OOB\fP
est renvoyé pour indiquer que des données prioritaires ou hors\-bande ont été
reçues.
.TP
\fBMSG_ERRQUEUE\fP
indique qu'aucune donnée n'a été reçue, sauf une erreur étendue depuis la
file d'erreurs.
.SH "VALEUR RENVOYÉE"
Ces appels renvoient le nombre d'octets reçus si elles réussissent, ou \fB\-1\fP
si elles échouent. Dans ce dernier cas, \fIerrno\fP permettra d'identifier la
cause de l'erreur.
.PP
Lorsque le partenaire d'un socket de flux se ferme proprement, la valeur
renvoyée est \fB0\fP (c'est\-à\-dire la valeur habituellement renvoyée lorsqu'on
arrive à la fin d'un fichier).
.PP
Les sockets de datagrammes autorisent des datagrammes de longueur nulle dans
différents domaines (par exemple, les domaines UNIX et Internet). Lorsque de
tels datagrammes sont reçus, la valeur renvoyée est \fB0\fP.
.PP
La valeur \fB0\fP peut aussi être renvoyée lorsque le nombre d'octets demandé
en réception d'un socket de flux est égal à \fB0\fP.
.SH ERREURS
Voici quelques erreurs standards déclenchées par la couche socket. Des
erreurs supplémentaires peuvent être générées et renvoyées par des modules
du protocole sous\-jacent. Consultez leurs pages de manuel.
.TP
\fBEAGAIN\fP ou \fBEWOULDBLOCK\fP
.\" Actually EAGAIN on Linux
Le socket est indiqué comme non bloquant et l'opération de réception
bloquerait ou un délai de réception a été indiqué et il a expiré sans que
l'on ait reçu quoi que ce soit. POSIX.1 autorise de renvoyer l'une ou
l'autre des erreurs dans ce cas et n'exige pas que ces constantes aient la
même valeur. Une application portable devrait donc tester les deux
possibilités.
.TP
\fBEBADF\fP
Le paramètre \fIsockfd\fP est un descripteur de fichier non valable.
.TP
\fBECONNREFUSED\fP
Un hôte distant a refusé la connexion réseau (généralement parce qu'il
n'offre pas le service demandé).
.TP
\fBEFAULT\fP
Un tampon pointe en dehors de l'espace d'adressage accessible.
.TP
\fBEINTR\fP
Un signal a interrompu la réception avant que des données soient
disponibles\ ; consultez \fBsignal\fP(7).
.TP
\fBEINVAL\fP
.\" e.g., msg_namelen < 0 for recvmsg() or addrlen < 0 for recvfrom()
Un paramètre non valable a été fourni.
.TP
\fBENOMEM\fP
Pas assez de mémoire pour \fBrecvmsg\fP().
.TP
\fBENOTCONN\fP
Le socket est associé à un protocole orienté connexion et n'a pas encore été
connecté (consultez \fBconnect\fP(2) et \fBaccept\fP(2)).
.TP
\fBENOTSOCK\fP
Le descripteur de fichier \fIsockfd\fP ne fait pas référence à un socket.
.SH STANDARDS
POSIX.1\-2001, POSIX.1\-2008, 4.4BSD (les interfaces sont apparues pour la
première fois dans 4.2BSD).
.PP
POSIX.1 décrit seulement les drapeaux \fBMSG_OOB\fP, \fBMSG_PEEK\fP et
\fBMSG_WAITALL\fP.
.SH NOTES
Si un datagramme de taille nulle est en attente, \fBread\fP(2) et \fBrecv\fP()
avec un paramètre \fIflags\fP vide, donne un comportement différent. Dans ce
cas, \fBread\fP(2) n'a aucun effet (le datagramme reste en attente) alors que
\fBrecv\fP() consomme le datagramme en attente.
.PP
Le type \fIsocklen_t\fP a été inventé par POSIX. Voir aussi \fBaccept\fP(2).
.PP
.\" POSIX.1-2001, POSIX.1-2008
.\" glibc bug for msg_controllen raised 12 Mar 2006
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
.\" The problem is an underlying kernel issue: the size of the
.\" __kernel_size_t type used to type these fields varies
.\" across architectures, but socklen_t is always 32 bits,
.\" as (at least with GCC) is int.
Selon POSIX.1, le champ \fImsg_controllen\fP de la structure \fImsghdr\fP devrait
être de type \fIsocklen_t\fP et le champ \fImsg_iovlen\fP devrait être de type
\fIint\fP, mais ils ont tous deux le type \fIsize_t\fP dans la glibc.
.PP
Consultez \fBrecvmmsg\fP(2) pour plus d'informations au sujet d'un appel
système propre à Linux, utilisé pour recevoir des datagrammes multiples avec
un unique appel.
.SH EXEMPLES
Un exemple d'utilisation de \fBrecvfrom\fP() se trouve dans la page de manuel
de \fBgetaddrinfo\fP(3).
.SH "VOIR AUSSI"
\fBfcntl\fP(2), \fBgetsockopt\fP(2), \fBread\fP(2), \fBrecvmmsg\fP(2), \fBselect\fP(2),
\fBshutdown\fP(2), \fBsocket\fP(2), \fBcmsg\fP(3), \fBsockatmark\fP(3), \fBip\fP(7),
\fBipv6\fP(7), \fBsocket\fP(7), \fBtcp\fP(7), \fBudp\fP(7), \fBunix\fP(7)
.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>,
Cédric Boutillier <cedric.boutillier@gmail.com>,
Frédéric Hantrais <fhantrais@gmail.com>
et
Jean-Philippe MENGUAL <jpmengual@debian.org>
.
.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 .