plucky (2) recvmsg.2.gz

Provided by: manpages-fr-dev_4.25.1-1_all bug

NOM

       recv, recvfrom, recvmsg - Recevoir un message d'un socket

BIBLIOTHÈQUE

       Bibliothèque C standard (libc, -lc)

SYNOPSIS

       #include <sys/socket.h>

       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  système  recv(),  recvfrom() et recvmsg() 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.

       La  seule  différence  entre  recv() et read(2) est la présence de flags. Si l’argument flags est absent,
       recv() est généralement équivalent à read(2) (mais voir les NOTES). De plus, l'appel suivant

           recv(sockfd, buf, len, flags);

       est équivalent à :

           recvfrom(sockfd, buf, len, flags, NULL, NULL);

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

       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  fcntl(2)), auquel cas la valeur -1 est renvoyée et errno est
       positionnée  à  EAGAIN  ou  EWOULDBLOCK.  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é.

       Une  application  peut  avoir  recours  à  select(2),  poll(2),  ou  epoll(7)  pour savoir si des données
       supplémentaires arrivent dans le socket.

   Le paramètre des attributs
       L'argument flags est constitué à 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  reçu  à  l’aide  d’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 l'opération non bloquante ; si  elle  bloque,  l'appel  échoue  avec  l'erreur  EAGAIN  ou
              EWOULDBLOCK.  Cela  fournit  un comportement identique à la définition de l'attribut O_NONBLOCK (à
              l'aide de l'opération F_SETFL de fcntl(2)), sauf que MSG_DONTWAIT est une option pour chaque appel
              tandis  que  O_NONBLOCK  est un paramètre sur la description du fichier ouvert (voir open(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.

       MSG_ERRQUEUE (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 (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.

              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 d’attente. ee_origin  est  le  code  d'origine
              d’où  l’erreur  provient. Les autres champs sont spécifiques au protocole. La macro SO_EE_OFFENDER
              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 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.

              Pour  les  erreurs  locales,  aucune  adresse  n'est passée (cela 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  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.

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

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

       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 ordonnés (depuis Linux 3.4) : 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 de flux Internet, consultez tcp(7).

       MSG_WAITALL (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.

   recvfrom()
       recvfrom()  enregistre  le message reçu dans le tampon buf. Le processus appelant doit préciser 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
       insérée dans le tampon désigné par src_addr. Dans ce cas, addrlen est un paramètre valeur-résultat. Avant
       l'appel, il doit être initialisé à la valeur de la taille  du  tampon  associé  à  src_addr.  En  retour,
       addrlen 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 addrlen renvoie un valeur supérieure à  celle  fournie
       lors de l'appel.

       Si  le  processus  appelant  n'est  pas intéressé par l'adresse de la source, src_addr et addrlen doivent
       avoir la valeur NULL.

   recv()
       L'appel recv() est normalement utilisé sur un socket connecté (voir  connect(2)).  Il  est  équivalent  à
       l'appel :

           recvfrom(fd, buf, len, flags, NULL, 0);

   recvmsg()
       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 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‐dessous */
               size_t        msg_controllen; /* Taille du tampon de données annexe */
               int           msg_flags;      /* Attributs du message reçu */
           };

       Le champ msg_name 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 msg_namelen avec la taille de ce
       tampon avant l'appel ; si l'appel s'exécute avec succès,  msg_name  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 à msg_name.

       Les champs msg_iov et msg_iovlen décrivent les emplacements de  dispersion-regroupement  (scatter-gather)
       tels qu'expliqués dans readv(2).

       Le  champ  msg_control, de longueur msg_controllen, pointe sur un tampon utilisé pour les autres messages
       du  protocole  relatifs  au  contrôle,  ou  à  d'autres  données  annexes.  Lorsqu'on  invoque   recvmsg,
       msg_controllen  doit  contenir  la  longueur  du tampon disponible dans msg_control ; lors du retour d’un
       appel réussi,il contiendra la longueur de la séquence du message de contrôle.

       Les messages ont la forme

           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[]; */
           };

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

       À 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 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  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
              est renvoyé pour indiquer que des données prioritaires ou 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.

       MSG_CMSG_CLOEXEC (depuis Linux 2.6.23)
              indique que MSG_CMSG_CLOEXEC a été spécifié dans l'argument flags de recvmsg().

VALEUR RENVOYÉE

       Ces  appels  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.

       Lorsque le partenaire d'un socket de flux se ferme proprement, la valeur renvoyée est 0 (c'est-à-dire  la
       valeur habituellement renvoyée lorsqu'on arrive à la fin d'un fichier).

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

       La  valeur 0 peut aussi être renvoyée lorsque le nombre d'octets demandé en réception d'un socket de flux
       est égal à 0.

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.

       EAGAIN ou EWOULDBLOCK
              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.

       EBADF  Le paramètre sockfd est un descripteur de fichier non valable.

       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  réception  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
              Le socket est associé à un protocole orienté connexion et n'a pas encore été  connecté  (consultez
              connect(2) et accept(2)).

       ENOTSOCK
              Le descripteur de fichier sockfd ne fait pas référence à un socket.

VERSIONS

       Selon  POSIX.1, le champ msg_controllen de la structure msghdr devrait être de type socklen_t et le champ
       msg_iovlen devrait être 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 décrit 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 paramètre flags vide, donne un
       comportement  différent.  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 système propre à Linux,  utilisé  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  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>

       Cette traduction est une documentation libre ; veuillez vous reporter à la  GNU  General  Public  License
       version 3   ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩   concernant   les  conditions  de  copie  et  de
       distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

       Si vous découvrez un bogue dans la traduction de cette page de manuel,  veuillez  envoyer  un  message  à
       ⟨debian-l10n-french@lists.debian.org⟩.