Provided by: manpages-fr-dev_3.27fr1.4-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 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)