recv(2) System Calls Manual recv(2) NOM recv, recvfrom, recvmsg - Recevoir un message d'un socket BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include ssize_t recv(int sockfd, void buf[.len], size_t len, int flags); ssize_t recvfrom(int sockfd, void buf[restrict .len], size_t len, int flags, struct sockaddr *_Nullable restrict src_addr, socklen_t *_Nullable restrict addrlen); ssize_t recvmsg(int sockfd, struct msghdr *msg, int flags); DESCRIPTION Les appels systeme recv(), recvfrom() et recvmsg() sont utilises pour recevoir des messages depuis un socket, et peuvent servir sur un socket oriente connexion ou non. Cette page decrit dans un premier temps les fonctionnalites communes de ces trois appels systeme, puis precise ensuite ce qui les differencie. La seule difference entre recv() et read(2) est la presence de flags. Si l'argument flags est absent, recv() est generalement equivalent a read(2) (mais voir les NOTES). De plus, l'appel suivant recv(sockfd, buf, len, flags); est equivalent a : recvfrom(sockfd, buf, len, flags, NULL, NULL); Ces trois appels renvoient la longueur du message s'ils reussissent. Si un message est trop long pour tenir dans le tampon, les octets supplementaires peuvent etre abandonnes suivant le type de socket utilise. Si aucun message n'est disponible sur le socket, les appels a reception se mettent en attente, a moins que le socket soit non bloquant (voir fcntl(2)), auquel cas la valeur -1 est renvoyee et errno est positionnee a EAGAIN ou EWOULDBLOCK. Les appels a reception renvoient normalement les donnees disponibles, jusqu'au montant demande, sans attendre d'avoir recu le nombre exact reclame. Une application peut avoir recours a select(2), poll(2), ou epoll(7) pour savoir si des donnees supplementaires arrivent dans le socket. Le parametre des attributs L'argument flags est constitue a partir d'un OU binaire entre une ou plusieurs des valeurs suivantes : MSG_CMSG_CLOEXEC (recvmsg() uniquement ; depuis Linux 2.6.23) Positionner l'attribut << close-on-exec >> pour le descripteur de fichier recu a l'aide d'un descripteur de fichier de domaine UNIX en utilisant l'operation SCM_RIGHTS (decrite dans unix(7)). Cet attribut est utile pour les memes raisons que l'attribut O_CLOEXEC de open(2). MSG_DONTWAIT (depuis Linux 2.2) Activer l'operation non bloquante ; si elle bloque, l'appel echoue avec l'erreur EAGAIN ou EWOULDBLOCK. Cela fournit un comportement identique a la definition de l'attribut O_NONBLOCK (a l'aide de l'operation F_SETFL de fcntl(2)), sauf que MSG_DONTWAIT est une option pour chaque appel tandis que O_NONBLOCK est un parametre sur la description du fichier ouvert (voir open(2)), qui touchera tous les threads du processus appelant ainsi que d'autres processus detenant des descripteurs de fichier se rapportant a la meme description de fichier ouvert. MSG_ERRQUEUE (depuis Linux 2.2) Cet attribut demande que les erreurs soient recues depuis la file d'erreur du socket. Les erreurs sont transmises dans un message annexe dont le type depend du protocole (IP_RECVERR pour IPv4). Il faut alors fournir un tampon de taille suffisante. Consultez cmsg(3) et ip(7) pour plus de details. Le contenu du paquet original qui a cause l'erreur est passe en tant que donnees normales dans msg_iovec. L'adresse de destination originale du datagramme ayant cause l'erreur est fournie dans msg_name. L'erreur est contenue dans une structure sock_extended_err : #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; /* numero 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; /* donnees supplementaires */ uint32_t ee_data; /* autres donnees */ /* Des donnees supplementaires peuvent suivre */ }; struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *); ee_errno contient le code errno de l'erreur en file d'attente. ee_origin est le code d'origine d'ou l'erreur provient. Les autres champs sont specifiques au protocole. La macro SO_EE_OFFENDER renvoie un pointeur sur l'adresse de l'objet reseau ayant declenche l'erreur, en donnant un pointeur sur le message annexe. Si cette adresse n'est pas connue, le membre sa_family de la structure sockaddr contient AF_UNSPEC et les autres champs de la structure sockaddr sont indefinis. Le contenu du paquet ayant declenche l'erreur est transmis en donnees normales. Pour les erreurs locales, aucune adresse n'est passee (cela peut etre verifie dans le membre cmsg_len de cmsghdr). A la reception d'une erreur, MSG_ERRQUEUE est place dans msghdr. Apres reception d'une erreur, l'erreur en attente sur le socket est regeneree en fonction de la prochaine erreur dans la file et sera transmise lors de l'operation suivante sur le socket. MSG_OOB Cette option demande la reception de donnees hors-bande qui ne seraient pas recues dans le flux normal de donnees. Certains protocoles placent ces donnees hors-bande en tete de la file normale, et cette option n'a pas lieu d'etre dans ce cas. MSG_PEEK Cette option fait que l'operation de reception renvoie les donnees du debut de la queue de reception sans les enlever de cette file. Ainsi un appel a reception ulterieur renverra a nouveau les memes donnees. MSG_TRUNC (depuis Linux 2.2) Pour les sockets bruts (AF_PACKET), les sockets de datagrammes Internet (depuis Linux 2.4.27/2.6.8), de netlink (depuis Linux 2.6.22) et des datagrammes UNIX ainsi que pour ceux des paquets ordonnes (depuis Linux 3.4) : renvoyer la taille reelle du paquet ou datagramme, meme quand il est plus grand que le tampon fourni. Pour une utilisation avec des sockets de flux Internet, consultez tcp(7). MSG_WAITALL (depuis Linux 2.2) Ce drapeau demande que l'operation de lecture soit bloquee jusqu'a ce que la requete complete soit satisfaite. Toutefois, la lecture peut renvoyer quand meme moins de donnees que prevu si un signal est recu, si une erreur ou une deconnexion se produisent ou si les donnees suivantes a recevoir sont d'un type different de celles renvoyees. Ce drapeau n'a aucun effet sur les sockets de datagramme. recvfrom() recvfrom() enregistre le message recu dans le tampon buf. Le processus appelant doit preciser la taille de ce tampon dans len. Si src_addr n'est pas NULL, et si le protocole sous-jacent fournit l'adresse de la source, celle-ci y est inseree dans le tampon designe par src_addr. Dans ce cas, addrlen est un parametre valeur-resultat. Avant l'appel, il doit etre initialise a la valeur de la taille du tampon associe a src_addr. En retour, addrlen est mis a jour avec la valeur reelle de l'adresse source. Cette adresse est tronquee si le tampon fourni n'a pas une taille suffisante ; dans ce cas addrlen renvoie un valeur superieure a celle fournie lors de l'appel. Si le processus appelant n'est pas interesse par l'adresse de la source, src_addr et addrlen doivent avoir la valeur NULL. recv() L'appel recv() est normalement utilise sur un socket connecte (voir connect(2)). Il est equivalent a l'appel : recvfrom(fd, buf, len, flags, NULL, 0); recvmsg() L'appel recvmsg() utilise une structure msghdr pour minimiser le nombre de parametres a fournir directement. Cette structure est definie dans comme ceci : 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'elements dans msg_iov */ void *msg_control; /* Donnees annexes, voir ci-dessous */ size_t msg_controllen; /* Taille du tampon de donnees annexe */ int msg_flags; /* Attributs du message recu */ }; Le champ msg_name pointe vers un tampon alloue par l'appelant et qui est utilise pour renvoyer l'adresse source lorsque le socket n'est pas connecte. L'appelant doit initialiser msg_namelen avec la taille de ce tampon avant l'appel ; si l'appel s'execute avec succes, msg_name prend pour valeur la longueur de l'adresse renvoyee. Si l'application n'a pas besoin de connaitre l'adresse source, on peut affecter la valeur NULL a msg_name. Les champs msg_iov et msg_iovlen decrivent les emplacements de dispersion-regroupement (scatter-gather) tels qu'expliques dans readv(2). Le champ msg_control, de longueur msg_controllen, pointe sur un tampon utilise pour les autres messages du protocole relatifs au controle, ou a d'autres donnees annexes. Lorsqu'on invoque recvmsg, msg_controllen doit contenir la longueur du tampon disponible dans msg_control ; lors du retour d'un appel reussi,il contiendra la longueur de la sequence du message de controle. Les messages ont la forme struct cmsghdr { size_t cmsg_len; /* nombre d'octets de donnees, y compris l'en-tete (de type socklen_t dans POSIX) */ int cmsg_level; /* protocole d'origine */ int cmsg_type; /* type dependant du protocole */ /* suivi de unsigned char cmsg_data[]; */ }; Les donnees annexes ne doivent etre manipulees qu'avec les macros de cmsg(3). A titre d'exemple, Linux utilise ce mecanisme de donnees annexes pour transmettre des erreurs etendues, des options IP ou des descripteurs de fichier sur des sockets de domaine UNIX. Pour plus d'informations sur l'utilisation de ce mecanisme sur divers domaines de socket, voir unix(7) et ip(7). Le champ msg_flags du msghdr est rempli au retour de recvmsg(). Il peut contenir plusieurs attributs : MSG_EOR indique une fin d'enregistrement, les donnees recues terminent un enregistrement (utilise generalement avec les sockets du type SOCK_SEQPACKET). MSG_TRUNC indique que la portion finale du datagramme a ete abandonnee car le datagramme etait trop long pour le tampon fourni. MSG_CTRUNC indique que des donnees de controle ont ete abandonnees a cause d'un manque de place dans le tampon de donnees annexes. MSG_OOB est renvoye pour indiquer que des donnees prioritaires ou hors-bande ont ete recues. MSG_ERRQUEUE indique qu'aucune donnee n'a ete recue, sauf une erreur etendue depuis la file d'erreurs. MSG_CMSG_CLOEXEC (depuis Linux 2.6.23) indique que MSG_CMSG_CLOEXEC a ete specifie dans l'argument flags de recvmsg(). VALEUR RENVOYEE Ces appels renvoient le nombre d'octets recus si elles reussissent, ou -1 si elles echouent. Dans ce dernier cas, errno permettra d'identifier la cause de l'erreur. Lorsque le partenaire d'un socket de flux se ferme proprement, la valeur renvoyee est 0 (c'est-a-dire la valeur habituellement renvoyee lorsqu'on arrive a la fin d'un fichier). Les sockets de datagrammes autorisent des datagrammes de longueur nulle dans differents domaines (par exemple, les domaines UNIX et Internet). Lorsque de tels datagrammes sont recus, la valeur renvoyee est 0. La valeur 0 peut aussi etre renvoyee lorsque le nombre d'octets demande en reception d'un socket de flux est egal a 0. ERREURS Voici quelques erreurs standards declenchees par la couche socket. Des erreurs supplementaires peuvent etre generees et renvoyees par des modules du protocole sous-jacent. Consultez leurs pages de manuel. EAGAIN ou EWOULDBLOCK Le socket est indique comme non bloquant et l'operation de reception bloquerait ou un delai de reception a ete indique et il a expire sans que l'on ait recu 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 meme valeur. Une application portable devrait donc tester les deux possibilites. EBADF Le parametre sockfd est un descripteur de fichier non valable. ECONNREFUSED Un hote distant a refuse la connexion reseau (generalement parce qu'il n'offre pas le service demande). EFAULT Un tampon pointe en dehors de l'espace d'adressage accessible. EINTR Un signal a interrompu la reception avant que des donnees soient disponibles ; consultez signal(7). EINVAL Un parametre non valable a ete fourni. ENOMEM Pas assez de memoire pour recvmsg(). ENOTCONN Le socket est associe a un protocole oriente connexion et n'a pas encore ete connecte (consultez connect(2) et accept(2)). ENOTSOCK Le descripteur de fichier sockfd ne fait pas reference a un socket. VERSIONS Selon POSIX.1, le champ msg_controllen de la structure msghdr devrait etre de type socklen_t et le champ msg_iovlen devrait etre de type int, mais ils ont tous deux le type size_t dans la glibc. STANDARDS POSIX.1-2008. HISTORIQUE POSIX.1-2001, 4.4BSD (apparu dans 4.2BSD). POSIX.1 decrit seulement les drapeaux MSG_OOB, MSG_PEEK et MSG_WAITALL. NOTES Si un datagramme de taille nulle est en attente, read(2) et recv() avec un parametre flags vide, donne un comportement different. Dans ce cas, read(2) n'a aucun effet (le datagramme reste en attente) alors que recv() consomme le datagramme en attente. Consultez recvmmsg(2) pour plus d'informations au sujet d'un appel systeme propre a Linux, utilise pour recevoir des datagrammes multiples avec un unique appel. EXEMPLES Un exemple d'utilisation de recvfrom() se trouve dans la page de manuel de getaddrinfo(3). VOIR AUSSI fcntl(2), getsockopt(2), read(2), recvmmsg(2), select(2), shutdown(2), socket(2), cmsg(3), sockatmark(3), ip(7), ipv6(7), socket(7), tcp(7), udp(7), unix(7) TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot , Cedric Boutillier , Frederic Hantrais et Jean-Philippe MENGUAL Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 31 octobre 2023 recv(2)