Provided by:
manpages-fr-dev_3.27fr1.4-1_all 
NOM
recv, recvfrom, recvmsg - Recevoir un message sur une socket
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
ssize_t recv(int sockfd, void *buf, size_t len, int flags);
ssize_t recvfrom(int sockfd, void *buf, size_t len, int flags,
struct sockaddr *src_addr, socklen_t *addrlen);
ssize_t recvmsg(int sockfd, struct msghdr *msg, int flags);
DESCRIPTION
Les appels systeme recvfrom() et recvmsg() sont utilises pour recevoir
des messages depuis une socket, et peuvent servir sur une socket
orientee connexion ou non.
Si src_addr n'est pas NULL, et si le protocole sous-jacent fournit
l'adresse de la source, celle-ci y est inseree. Quand src_addr vaut
NULL, rien n'est insere ; dans ce cas, addrlen n'est pas utilise et
devrait egalement valoir NULL. addrlen est un parametre resultat,
initialise a la taille du tampon src_addr, et modifie en retour pour
indiquer la taille reelle de l'adresse enregistree. L'adresse renvoyee
est tronquee si le tampon fourni est trop petit ; dans ce cas, addrlen
renverra une valeur superieure a celle fourni lors de l'appel.
L'appel recv() est normalement utilise sur une socket connect'ee (voir
connect(2)) et est equivalent a recvfrom() avec un parametre src_addr
NULL.
Ces trois routines renvoient la longueur du message si elles
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 la socket, les fonctions de
reception se mettent en attente, a moins que la socket soit non
bloquante (voir fcntl(2)) auquel cas la valeur -1 est renvoyee, et
errno est positionnee a EAGAIN ou EWOULDBLOCK. Les fonctions de
reception renvoient normalement les donnees disponibles sans attendre
d'avoir recu le nombre exact reclame.
Les appels systeme select(2) ou poll(2) peuvent permettre de determiner
si des donnees supplementaires sont disponibles.
L'argument flags de l'appel recv() est constitue par un OU binaire
entre une ou plusieurs des valeurs suivantes :
MSG_CMSG_CLOEXEC (recvmsg() uniquement ; depuis Linux 2.6.23)
Positionne l'attribut << close-on-exec >> pour le descripteur de
fichier recu via 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 les operations non bloquantes. Si l'operation devait
bloquer, l'appel echouera avec l'erreur EAGAIN ou EWOULDBLOCK
(on peut aussi activer ce comportement avec l'option O_NONBLOCK
de la fonction F_SETFL de fcntl(2)).
MSG_ERRQUEUE (depuis Linux 2.2)
Cet attribut demande que les erreurs soient recues depuis la
file d'erreur de la 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.
Pour les erreurs locales, aucune adresse n'est passee (ceci 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 la socket est
regeneree en fonction de la prochaine erreur dans la file, et
sera transmise lors de l'operation suivante sur la socket.
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. ee_origin
est le code d'origine de l'erreur. Les autres champs sont
specifiques au protocole. La macro SOCK_EE_OFFENDER renvoie un
pointeur sur l'adresse de l'objet reseau ayant declenche
l'erreur, a partir d'un pointeur sur le message. Si l'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 (ceci 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 la socket est
regeneree en fonction de la prochaine erreur dans la file, et
sera transmise lors de l'operation suivante sur la socket.
MSG_OOB
Cette option permet la lecture des donnees hors-bande qui ne
seraient autrement pas placees dans le flux de donnees normales.
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 permet de lire les donnees en attente dans la file
sans les enlever de cette file. Ainsi une lecture ulterieure
renverra a nouveau les memes donnees.
MSG_TRUNC (depuis Linux 2.2)
Pour les socket en mode brut (AF_PACKET), datagramme Internet
(depuis Linux 2.4.27/2.6.8) et netlink (depuis Linux 2.6.22) :
renvoyer la taille reelle du paquet ou datagramme, meme quand il
est plus grand que le tampon fourni. Ce n'est pas implemente
pour les sockets de domaine Unix (unix(7)).
Pour une utilisation avec des sockets en mode flux, consultez
tcp(7).
MSG_WAITALL (depuis Linux 2.2)
Cette option 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, ou si une erreur ou une deconnexion se
produisent.
L'appel recvmsg() utilise une structure msghdr pour minimiser le nombre
de parametres a fournir directement. Cette structure est definie dans
<sys/socket.h> comme ceci :
struct iovec { /* dispersion/assemblage
d'elements de tableaux */
void *iov_base; /* Adresse de debut */
size_t iov_len; /* Nombre d'octets a transferer */
};
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; /* # elements dans msg_iov */
void *msg_control; /* metadonnees, voir ci-dessous */
size_t msg_controllen; /* taille du tampon de metadonnees */
int msg_flags; /* attributs du message recu */
};
Ici msg_name et msg_namelen specifient l'adresse d'origine si la socket
n'est pas connectee ; msg_name peut etre un pointeur nul si le nom
n'est pas necessaire. msg_iov et msg_iovlen decrivent les tampons de
reception comme decrit dans readv(2). msg_control, de longueur
msg_controllen, pointe sur un tampon utilise pour les autres messages
relatifs au protocole, ou a d'autres donnees annexes. Lorsqu'on invoque
recvmsg, msg_controllen doit contenir la longueur disponible dans le
tampon msg_control ; au retour il contiendra la longueur de la sequence
de message de controle.
Les messages ont la forme
struct cmsghdr {
socklen_t cmsg_len; /* nombre d'octets de donnees, y compris l'en-tete */
int cmsg_level; /* protocole d'origine */
int cmsg_type; /* type dependant du protocole */
/* suivi de
unsigned char cmsg_data[]; */
};
Les donnees de service ne doivent etre manipulees qu'avec les macros de
cmsg(3).
A titre d'exemple, Linux utilise ce mecanisme pour transmettre des
erreurs etendues, des options IP, ou des descripteurs de fichier sur
des sockets Unix.
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
indique que des donnees hors-bande ont ete recues.
MSG_ERRQUEUE
indique qu'aucune donnee n'a ete recue, sauf une erreur etendue
depuis la file d'erreurs.
VALEUR RENVOY'EE
Ces fonctions renvoient le nombre d'octets recus si elles reussissent,
ou -1 si elles echouent. La valeur de retour sera 0 si le pair a
effectue un arret normal.
ERREURS
Il y a des erreurs standards declenchees par le niveau socket, et des
erreurs supplementaires specifiques aux protocoles. Consultez leurs
pages de manuel.
EAGAIN ou EWOULDBLOCK
La socket est non bloquante et aucune donnee n'est disponible,
ou un delai de timeout a ete indique, et il a expire sans que
l'on ait recu quoi que ce soit. POSIX.1-2001 permet 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 n'est pas un descripteur correct.
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 lecture 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
La socket est associee a un protocole oriente connexion et n'a
pas encore ete connectee (consultez connect(2) et accept(2)).
ENOTSOCK
Le parametre sockfd ne correspond pas a une socket.
CONFORMIT'E
BSD 4.4 (ces fonctions sont apparues dans BSD 4.2), POSIX.1-2001.
POSIX.1-2001 decrit seulement les drapeaux MSG_OOB, MSG_PEEK, et
MSG_WAITALL.
NOTES
Les prototypes fournis concernent la glibc 2. Les Specifications Single
Unix les definissent, mais le type de retour est ssize_t (alors que
BSD 4.x, libc4 , et libc5 renvoient un int). L'argument flags est un
int dans BSD 4.x, mais unsigned int dans libc4 et libc5. L'argument len
est un int dans BSD 4.x, mais un size_t dans libc4 et libc5. L'argument
addrlen est un int * dans BSD 4.x, libc4 et libc5. Le socklen_t *
actuel a ete invente par POSIX. Consultez egalement accept(2).
Selon POSIX.1-2001, le champ msg_controllen de la structure msghdr
devrait etre de type socklen_t, mais il a actuellement le type size_t
dans la glibc.
EXEMPLE
Un exemple d'utilisation de recvfrom() se trouve dans la page de manuel
de getaddrinfo(3).
VOIR AUSSI
fcntl(2), getsockopt(2), read(2), select(2), shutdown(2), socket(2),
cmsg(3), sockatmark(3), socket(7)
COLOPHON
Cette page fait partie de la publication 3.27 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent etre trouvees a l'adresse
<URL:http://www.kernel.org/doc/man-pages/>.
TRADUCTION
Depuis 2010, cette traduction est maintenue a l'aide de l'outil po4a
<URL:http://po4a.alioth.debian.org/> par l'equipe de traduction
francophone au sein du projet perkamon
<URL:http://perkamon.alioth.debian.org/>.
Christophe Blaess <URL:http://www.blaess.fr/christophe/> (1996-2003),
Alain Portal <URL:http://manpagesfr.free.fr/> (2003-2006). Julien
Cristau et l'equipe francophone de traduction de Debian (2006-2009).
Veuillez signaler toute erreur de traduction en ecrivant a
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir acces a la version anglaise de ce document
en utilisant la commande << man -L C <section> <page_de_man> >>.
Linux 29 aout 2010 RECV(2)