Ubuntu Manpage: recv, recvfrom, recvmsg - Recevoir un message sur une socket

Provided by: manpages-fr-dev_3.57d1p1-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 système recvfrom() et recvmsg() sont utilisés pour recevoir des messages depuis
une socket, et peuvent servir sur une socket orientée 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 insérée. Quand src_addr vaut NULL, rien n'est inséré ; dans ce cas, addrlen
n'est pas utilisé et devrait également valoir NULL. addrlen est un paramètre résultat,
initialisé à la taille du tampon src_addr, et modifié en retour pour indiquer la taille
réelle de l'adresse enregistrée. L'adresse renvoyée est tronquée si le tampon fourni est
trop petit ; dans ce cas, addrlen renverra une valeur supérieure à celle fourni lors de
l'appel.

L'appel recv() est normalement utilisé sur une socket connectée (voir connect(2)) et est
équivalent à recvfrom() avec un paramètre src_addr NULL.

Ces trois routines renvoient la longueur du message si elles 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é.

Si aucun message n'est disponible sur la socket, les fonctions de réception se mettent en
attente, à moins que la socket soit non bloquante (voir fcntl(2)) auquel cas la valeur -1
est renvoyée, et errno est positionnée à EAGAIN ou EWOULDBLOCK. Les fonctions de réception
renvoient normalement les données disponibles sans attendre d'avoir reçu le nombre exact
réclamé.

Les appels système select(2) ou poll(2) peuvent permettre de déterminer si des données
supplémentaires sont disponibles.

L'argument flags de l'appel recv() est constitué 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 reçu via un
descripteur de fichier de domaine UNIX en utilisant l'opération SCM_RIGHTS (décrite
dans unix(7)). Cet attribut est utile pour les mêmes raisons que l'attribut
O_CLOEXEC de open(2).

MSG_DONTWAIT (depuis Linux 2.2)
Activer les opérations non bloquantes. Si l'opération devait bloquer, l'appel
échouera 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 reçues depuis la file d'erreur de la
socket. Les erreurs sont transmises dans un message annexe dont le type dépend du
protocole (IP_RECVERR pour IPv4). Il faut alors fournir un tampon de taille
suffisante. Consultez cmsg(3) et ip(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
msg_iovec. L'adresse de destination originale du datagramme ayant causé l'erreur
est fournie dans msg_name.

Pour les erreurs locales, aucune adresse n'est passée (ceci peut être vérifié dans
le membre cmsg_len de cmsghdr). À la réception d'une erreur, MSG_ERRQUEUE est placé
dans msghdr. Après réception d'une erreur, l'erreur en attente sur la 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 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; /* 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_errno contient le code errno de l'erreur en file. ee_origin est le code
d'origine de l'erreur. Les autres champs sont spécifiques au protocole. La macro
SOCK_EE_OFFENDER renvoie un pointeur sur l'adresse de l'objet réseau ayant
déclenché l'erreur, à 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 indéfinis. Le contenu du paquet ayant
déclenché l'erreur est transmis en données normales.

MSG_OOB
Cette option permet la lecture des données hors-bande qui ne seraient autrement pas
placées dans le flux de données normales. 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.

MSG_PEEK
Cette option permet de lire les données en attente dans la file sans les enlever de
cette file. Ainsi une lecture ultérieure renverra à nouveau les mêmes données.

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 réelle du
paquet ou datagramme, même quand il est plus grand que le tampon fourni.

Pour une utilisation avec des sockets en mode flux, consultez tcp(7).

MSG_WAITALL (depuis Linux 2.2)
Cette option 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, ou si une erreur ou une
déconnexion se produisent.

L'appel recvmsg() utilise une structure msghdr pour minimiser le nombre de paramètres à
fournir directement. Cette structure est définie dans <sys/socket.h> comme ceci :

struct iovec { /* dispersion/assemblage
d'éléments de tableaux */
void *iov_base; /* Adresse de début */
size_t iov_len; /* Nombre d'octets à transférer */
};

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; /* # éléments dans msg_iov */
void *msg_control; /* métadonnées, voir ci‐dessous */
size_t msg_controllen; /* taille du tampon de métadonnées */
int msg_flags; /* attributs du message reçu */
};

Ici msg_name et msg_namelen spécifient l'adresse d'origine si la socket n'est pas
connectée ; msg_name peut être un pointeur nul si le nom n'est pas nécessaire. msg_iov et
msg_iovlen décrivent les tampons de réception comme décrit dans readv(2). msg_control, de
longueur msg_controllen, pointe sur un tampon utilisé pour les autres messages relatifs au
protocole, ou à d'autres données 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 séquence de message de contrôle.

Les messages ont la forme

struct cmsghdr {
socklen_t cmsg_len; /* nombre d'octets de données, y compris l'en-tête */
int cmsg_level; /* protocole d'origine */
int cmsg_type; /* type dépendant du protocole */
/* suivi de
unsigned char cmsg_data[]; */
};

Les données de service ne doivent être manipulées qu'avec les macros de cmsg(3).

À titre d'exemple, Linux utilise ce mécanisme pour transmettre des erreurs étendues, des
options IP, ou des descripteurs de fichier sur des sockets de domaine 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 données reçues terminent un enregistrement
(utilisé généralement avec les sockets du type SOCK_SEQPACKET).

MSG_TRUNC
indique que la portion finale du datagramme a été abandonnée car le datagramme
était trop long pour le tampon fourni.

MSG_CTRUNC
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.

MSG_OOB
indique que des données hors-bande ont été reçues.

MSG_ERRQUEUE
indique qu'aucune donnée n'a été reçue, sauf une erreur étendue depuis la file
d'erreurs.

VALEUR RENVOYÉE

       Ces fonctions renvoient le nombre d'octets reçus si elles  réussissent,  ou  -1  si  elles
       échouent.  Dans  ce  dernier  cas,  errno  permettra d'identifier la cause de l'erreur. La
       valeur de retour sera 0 si le pair a effectué un arrêt normal.

ERREURS

       Il  y  a  des  erreurs  standards  déclenchées  par  le  niveau  socket,  et  des  erreurs
       supplémentaires spécifiques aux protocoles. Consultez leurs pages de manuel.

       EAGAIN ou EWOULDBLOCK
              La  socket  est  non  bloquante  et  aucune donnée n'est disponible, ou un délai de
              timeout a été indiqué, et il a expiré sans que l'on ait  reçu  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 même valeur. Une application portable devrait  donc
              tester les deux possibilités.

       EBADF  Le paramètre sockfd n'est pas un descripteur correct.

       ECONNREFUSED
              Un  hôte distant a refusé la connexion réseau (généralement parce qu'il n'offre pas
              le service demandé).

       EFAULT Un tampon pointe en dehors de l'espace d'adressage accessible.

       EINTR  Un signal a interrompu la  lecture  avant  que  des  données  soient  disponibles ;
              consultez signal(7).

       EINVAL Un paramètre non valable a été fourni.

       ENOMEM Pas assez de mémoire pour recvmsg().

       ENOTCONN
              La  socket  est  associée  à  un  protocole orienté connexion et n'a pas encore été
              connectée (consultez connect(2) et accept(2)).

       ENOTSOCK
              Le paramètre sockfd ne correspond pas à une socket.

CONFORMITÉ

       BSD 4.4 (ces fonctions sont apparues dans BSD 4.2), POSIX.1-2001.

       POSIX.1-2001 décrit seulement les drapeaux MSG_OOB, MSG_PEEK, et MSG_WAITALL.

NOTES

       Les prototypes  fournis  concernent  la  glibc  2.  Les  Spécifications  Single  UNIX  les
       définissent,  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  été
       inventé par POSIX. Consultez également accept(2).

       Selon  POSIX.1-2001,  le  champ msg_controllen de la structure msghdr devrait être de type
       socklen_t, mais il a actuellement le type size_t dans la glibc.

       Consultez recvmmsg(2) pour plus d'nformations au sujet d'un appel système propre à  Linux,
       utilisé pour recevoir des datagrammes multiples avec un unique appel.

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), recvmmsg(2), select(2), shutdown(2), socket(2), cmsg(3),
       sockatmark(3), socket(7)

COLOPHON

       Cette page fait partie de la publication 3.57 du projet man-pages Linux.  Une  description
       du  projet  et  des  instructions  pour  signaler  des  anomalies  peuvent être trouvées à
       l'adresse http://www.kernel.org/doc/man-pages/.

TRADUCTION

       Depuis   2010,   cette   traduction   est   maintenue   à   l'aide   de    l'outil    po4a
       <http://po4a.alioth.debian.org/>  par l'équipe de traduction francophone au sein du projet
       perkamon <http://perkamon.alioth.debian.org/>.

       Christophe   Blaess   <http://www.blaess.fr/christophe/>   (1996-2003),    Alain    Portal
       <http://manpagesfr.free.fr/>  (2003-2006).  Julien  Cristau  et  l'équipe  francophone  de
       traduction de Debian (2006-2009).

       Veuillez     signaler     toute     erreur     de     traduction     en     écrivant     à
       <debian-l10n-french@lists.debian.org>   ou   par   un  rapport  de  bogue  sur  le  paquet
       manpages-fr.

       Vous pouvez toujours avoir accès à la version anglaise de  ce  document  en  utilisant  la
       commande « man -L C <section> <page_de_man> ».