.\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)recv.2	6.11 (Berkeley) 5/1/91
.\"
.\" Modified Sat Jul 24 00:22:20 1993 by Rik Faith (faith@cs.unc.edu)
.\"
.\" Traduction 13/10/1996 par Christophe Blaess (ccb@club-internet.fr)
.\" Mise a Jour 08/04/1997
.\" Mise a Jour 19/07/1997
.\" Mise a Jour 18/05/1999 - LDP-man-pages-1.23
.TH RECV 2 "18 Mai 1999" Linux "Manuel du programmeur Linux"
.SH NOM
recv, recvfrom, recvmsg \- Recevoir un message sur une socket.
.SH SYNOPSIS
.B #include <sys/types.h>
.br
.B #include <sys/socket.h>
.sp 2
.BI "int recv(int " s ", void *" buf ", int " len ", unsigned int " flags );
.sp
.BI "int recvfrom(int " s ", void *" buf ", int " len ", unsigned int " flags
.BI "struct sockaddr *" from ", socklen_t *" fromlen );
.sp
.BI "int recvmsg(int " s ", struct msghdr *" msg ", unsigned int " flags );
.SH DESCRIPTION
.B recvfrom
et
.B recvmsg
sont utiliss pour recevoir des messages depuis une socket
.I s,
et peuvent servir  la lecture de donnes que la socket 
soit oriente connexion ou non.

Si
.I from
est non nul, et si la socket n'est pas oriente connexion, l'adresse
de la source du messages y est insre.
.I Fromlen
est un paramtre rsultat, initialis  la taille du buffer 
.IR from ,
et modifi en retour pour indiquer la taille relle de l'adresse
enregistre.

L'appel 
.B recv
est normalement utilis sur une socket
.I connecte
(voir
.BR connect (2))
et est quivalent  
.B recvfrom
avec un paramtre
.I from
nul.  Comme ceci est redondant il est possible que
.B recv
ne soit plus maintenu dans le futur.

Ces trois routines renvoient la longueur du message si elles
russissent. Si un message est trop long pour tenir dans le
buffer, les octets supplmentaires peuvent tre abandonns 
suivant le type de socket utilis (voir
.BR socket (2)).

Si aucun message n'est disponible sur la socket, les fonctions
de rception se mettent en attente,  moins que la socket
soit non bloquante (voir
.BR fcntl (2))
auquel cas la valeur  \-1 est renvoye, et
.I errno
est positionne 
.BR EWOULDBLOCK .

Les fonctions de rception renvoient normalement les donnes disponibles
dans la limite du paramtre
.I len
sans attendre d'avoir reu le nombre exact rclam. Ce comportement peut
tre modifi avec les options de socket
.B SO_RCVLOWAT
et
.B SO_RCVTIMEO
dcrites dans
.BR getsockopt (2).

L'appel 
.BR select (2)
peut permettre de dterminer si des donnes supplmentaires sont
disponibles.

L'argument
.I flags
de l'appel recv est constitu par un
.I OU binaire
( | )
entre les valeurs suivantes
.TP 0.8i
.TP
MSG_OOB
traiter les donnes hors-bande
.TP
MSG_PEEK
lire sans enlever les donnes
.TP
MSG_WAITALL
attendre le nombre exact ou une erreur

L'option
.B MSG_OOB
permet la lecture des donnes hors-bande qui ne seraient autrement
pas places dans le flux de donnes normales. Certains protocoles
placent ces donnes hors-bande en tte de la file normale, et cette
option n'a pas lieu d'tre dans ce cas.

L'option
.B MSG_PEEK
permet de lire les donnes en attente dans la file sans les enlever de
cette file. Ainsi une lecture ultrieure renverra  nouveau les
mmes donnes.

L'option
.B MSG_WAITALL
demande que l'opration de lecture soit bloque jusqu' ce que
la requte complte soit satisfaite. Toutefois la lecture peut 
renvoyer quand mme moins de donnes que prvu si un signal
est reu, ou si une erreur ou une dconnexion se produisent.

L'appel
.B recvmsg
utilise une structure
.I msghdr
pour minimiser le nombre de paramtres  fournir directement. Cette
structure  la forme suivante, dfinie dans 
.IR <sys/socket.h>

.RS
.nf
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 */
};
.fi
.RE

Ici
.I msg_name
et
.I msg_namelen
spcifient l'adresse destination si la socket n'est pas connecte,
.I msg_name
peut tre un pointeur nul si le nom n'est pas ncessaire.
.I Msg_iov
et
.I msg_iovlen
dcrivent les buffers de rception comme dcrit dans
.BR readv (2).
.IR Msg_control ,
de longueur
.IR msg_controllen ,
pointe sur un buffer utilis pour les autres messages relatifs au protocole,
ou  d'autres donnes annexes. Les messages ont la forme

.RS
.nf
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[]; */
};
.fi
.RE

Par exemple, on peut utiliser ceci pour tre informe des changements du
flux de donnes avec XNS/SPP, 
ou pour obtenir des donnes d'identification en demandant un recvmsg
sans buffer immdiatement aprs l'appel de
.B accept
avec ISO.

Les descripteurs de fichiers annexes sont dsormais passs
en tant que donnes annexes dans le domaine
.B AF_UNIX
avec
.I cmsg_level
valant
.B SOL_SOCKET
et
.I cmsg_type
valant
.BR SCM_RIGHTS .

Le champ
.I msg_flags
est rempli au retour avec les informations concernant le message.
.B MSG_EOR
indique une fin d'enregistrement, les donnes reues terminent un
enregistrement (utilis gnralement avec les sockets du type
.BR SOCK_SEQPACKET ).
.B MSG_TRUNC
indique que la portion finale du datagramme a t abandonne car le
datagramme tait trop long pour le buffer fourni.
.B MSG_CTRUNC
indique que des donnes de contrle ont t abandonnes  cause d'un 
manque de place dans le buffer de donnes annexes.
.B MSG_OOB
indique que des donnes hors-bande ont t reues.

.SH "VALEUR RENVOYE"
Ces fonctions
renvoient le nombre d'octets reus si elles russissent, 
ou \-1 si elles chouent, auquel cas
.I errno
contient le code d'erreur.
.SH ERREURS
.TP 0.8i
.B EBADF
L'argument
.I s
n'est pas un descripteur valide.
.TP
.B ENOTCONN
La socket est associe  un protocole orient connexion et
n'a pas encore t connecte (voir
.BR connect (2)
et
.BR accept (2)).
.TP
.B ENOTSOCK
L'argument
.I s
ne correspond pas  une socket.
.TP
.B EWOULDBLOCK
La socket est non\-bloquante et aucune donne n'est disponible, ou
un dlai de timeout a t indiqu, et il a expir sans que l'on ait
reu quoi que ce soit.
.TP
.B EINTR
Un signal a interrompu la lecture avant que des donnes soient 
disponibles.
.TP
.B EFAULT
Un buffer pointe en dehors de l'espace d'adressage accessible.
.SH CONFORMIT
4.4 BSD (ces fonctions sont apparues dans BSD 4.2).
.SH NOTE
Le sixime argument de
.B recvfrom
est en fait un int (et c'est ce qu'utilisent BSD 4.*, libc4 et libc5).
Une certaine confusion POSIX rsulte du "socklen_t" actuel. Les propositions
de standard n'ont pas encore t adoptes, mais glibc2 les suit dj et
utilise socklen_t. Pour plus de dtails voir
.BR accept (2).
.SH "VOIR AUSSI"
.BR fcntl "(2), " read "(2), " select "(2), " getsockopt "(2), " socket (2)

.SH TRADUCTION
Christophe Blaess, 1997.