Provided by: manpages-fr-dev_3.65d1p1-1_all bug

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  recv(), recvfrom() et recvmsg() sont utilisés pour recevoir des messages depuis une
       socket, et peuvent servir sur une socket orientée 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.

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

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

   L'argument flags
       L'argument flags est constitué d'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.

              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.

       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), netlink
              (depuis Linux 2.6.22) et datagramme 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.

              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.

   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 sur désigné par src_addr. Dans ce cas, addrlen est un paramètre-résultat. Avant
       l'appel, il doit recevoir 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 buffer 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 doit  avoir  la  valeur
       NULL, et addrlen doit valoir 0.

   recv()
       L'appel  recv()  est  normalement utilisé sur une socket connectée (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 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.

       Lorsque le partenaire d'une 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'une socket de flux
       est égal à 0.

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'informations 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.65 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> ».