RECV(2)            Manuel du programmeur Linux            RECV(2)


NOM
       recv,  recvfrom,  recvmsg  -  Recevoir  un message sur une
       socket.

SYNOPSIS
       #include <sys/types.h>
       #include <sys/socket.h>


       int recv(int s, void *buf, int len, unsigned int flags)
       int recvfrom(int s, void *buf, int len, unsigned int flags
       struct sockaddr *from, socklen_t *fromlen);

       int  recvmsg(int  s,  struct  msghdr  *msg,  unsigned  int
       flags);

DESCRIPTION
       recvfrom et recvmsg sont utilisés pour recevoir  des  mes­
       sages  depuis une socket s, et peuvent servir à la lecture
       de données que la socket soit orientée connexion ou non.

       Si from est non nul, et si la socket  n'est  pas  orientée
       connexion,  l'adresse  de  la  source  du  messages  y est
       insérée.  Fromlen est un paramètre résultat, initialisé  à
       la  taille du buffer from, et modifié en retour pour indi­
       quer la taille réelle de l'adresse enregistrée.

       L'appel recv est normalement utilisé sur une  socket  con­
       nectée (voir connect(2)) et est équivalent à recvfrom avec
       un paramètre from nul.  Comme ceci est  redondant  il  est
       possible que recv ne soit plus maintenu dans le futur.

       Ces  trois  routines  renvoient  la longueur du message si
       elles réussissent. Si un message est trop long pour  tenir
       dans  le  buffer,  les octets supplémentaires peuvent être
       abandonnés  suivant  le  type  de  socket  utilisé   (voir
       socket(2)).

       Si aucun message n'est disponible sur la socket, les fonc­
       tions 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  à
       EWOULDBLOCK.

       Les  fonctions  de  réception  renvoient  normalement  les
       données disponibles dans la limite du paramètre  len  sans
       attendre  d'avoir  reçu  le  nombre exact réclamé. Ce com­
       portement peut être modifié avec  les  options  de  socket
       SO_RCVLOWAT et SO_RCVTIMEO décrites dans getsockopt(2).

       L'appel  select(2)  peut  permettre  de  déterminer si des
       données supplémentaires sont disponibles.




Linux                      18 Mai 1999                          1





RECV(2)            Manuel du programmeur Linux            RECV(2)


       L'argument flags de l'appel recv est constitué par  un  OU
       binaire ( | ) entre les valeurs suivantes


       MSG_OOB traiter les données hors-bande

       MSG_PEEK
               lire sans enlever les données

       MSG_WAITALL
               attendre le nombre exact ou une erreur

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

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

               L'option  MSG_WAITALL  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 à la forme  suivante,
               définie dans <sys/socket.h>

               struct msghdr {
                    caddr_t   msg_name; /* optional address */
                    u_int     msg_namelen;   /* size of address */
                    struct    iovec *msg_iov;     /* scatter/gather array */
                    u_int     msg_iovlen;    /* # elements in msg_iov */
                    caddr_t   msg_control;   /* ancillary data, see below */
                    u_int     msg_controllen; /* ancillary data buffer len */
                    int  msg_flags;     /* flags on received message */
               };

       Ici  msg_name et msg_namelen spécifient l'adresse destina­
       tion 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  buffers  de  réception  comme
       décrit  dans  readv(2).  Msg_control, de longueur msg_con­
       trollen, pointe sur un buffer utilisé pour les autres mes­
       sages   relatifs  au  protocole,  ou  à  d'autres  données
       annexes. Les messages ont la forme



Linux                      18 Mai 1999                          2





RECV(2)            Manuel du programmeur Linux            RECV(2)


               struct cmsghdr {
                    u_int     cmsg_len; /* data byte count, including hdr */
                    int  cmsg_level;    /* originating protocol */
                    int  cmsg_type;     /* protocol-specific type */
               /* followed by
                    u_char    cmsg_data[]; */
               };

       Par exemple, on peut utiliser ceci pour être  informe  des
       changements  du  flux  de  données  avec  XNS/SPP, ou pour
       obtenir  des  données  d'identification  en  demandant  un
       recvmsg  sans buffer immédiatement après l'appel de accept
       avec ISO.

       Les descripteurs de fichiers annexes sont désormais passés
       en  tant  que données annexes dans le domaine AF_UNIX avec
       cmsg_level   valant   SOL_SOCKET   et   cmsg_type   valant
       SCM_RIGHTS.

       Le  champ msg_flags est rempli au retour avec les informa­
       tions concernant le  message.   MSG_EOR  indique  une  fin
       d'enregistrement,  les  données reçues terminent un enreg­
       istrement (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 buffer fourni.  MSG_CTRUNC indique que
       des données de contrôle ont été abandonnées à  cause  d'un
       manque  de  place  dans  le  buffer  de  données  annexes.
       MSG_OOB indique que des données hors-bande ont été reçues.


VALEUR RENVOYÉE
       Ces  fonctions renvoient le nombre d'octets reçus si elles
       réussissent, ou -1 si elles  échouent,  auquel  cas  errno
       contient le code d'erreur.

ERREURS
       EBADF   L'argument s n'est pas un descripteur valide.

       ENOTCONN
               La socket est associée à un protocole orienté con­
               nexion et n'a pas encore été connectée (voir  con­
               nect(2) et accept(2)).

       ENOTSOCK
               L'argument s ne correspond pas à une socket.

       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.

       EINTR   Un signal a interrompu la lecture  avant  que  des



Linux                      18 Mai 1999                          3





RECV(2)            Manuel du programmeur Linux            RECV(2)


               données soient disponibles.

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

CONFORMITÉ
       4.4 BSD (ces fonctions sont apparues dans BSD 4.2).

NOTE
       Le sixième argument de recvfrom est en  fait  un  int  (et
       c'est  ce qu'utilisent BSD 4.*, libc4 et libc5).  Une cer­
       taine confusion POSIX résulte du "socklen_t"  actuel.  Les
       propositions  de  standard  n'ont pas encore été adoptées,
       mais glibc2 les suit déjà et utilise socklen_t. Pour  plus
       de détails voir accept(2).

VOIR AUSSI
       fcntl(2), read(2), select(2), getsockopt(2), socket(2)


TRADUCTION
       Christophe Blaess, 1997.



































Linux                      18 Mai 1999                          4