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