.\" 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
.TH RECV 2 "19 Juillet 1997" BSD "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 ", int *" fromlen );
.sp
.BI "int recvmsg(int " s ", struct msghdr *" msg ", unsigned int " flags );
.SH DESCRIPTION
.B recvfrom
et
.B recvmsg
sont utilises pour recevoir des messages depuis une socket
.I s,
et peuvent servir a la lecture de donnees que la socket 
soit orientee connexion ou non.

Si
.I from
est non nul, et si la socket n'est pas orientee connexion, l'adresse
de la source du messages y est inseree.
.I Fromlen
est un parametre resultat, initialise a la taille du buffer 
.IR from ,
et modifie en retour pour indiquer la taille reelle de l'adresse
enregistree.

L'appel 
.B recv
est normalement utilise sur une socket
.I connectee
(voir
.BR connect (2))
et est equivalent a 
.B recvfrom
avec un parametre
.I from
nul.  Comme ceci est redondant il est possible que
.B recv
ne soit plus supporte dans le futur.

Ces trois routines renvoient la longueur du message si elles
reussissent. Si un message est trop long pour tenir dans le
buffer, les octets supplementaires peuvent etre abandonnes 
suivant le type de socket utilise (voir
.BR socket (2)).

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

Les fonctions de reception retourne normalement les donnees disponibles
dans la limite du parametre
.I len
sans attendre d'avoir recu le nombre exact reclame. Ce comportement peut
etre modifie avec les options de socket
.B SO_RCVLOWAT
et
.B SO_RCVTIMEO
decrites dans
.BR getsockopt (2).

L'appel 
.BR select (2)
peut permettre de determiner si des donnees supplementaires sont
disponibles.

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

L'option
.B MSG_OOB
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.

L'option
.B MSG_PEEK
permet de lire les donnees en attente dans la file sans les enlever de
cette file. Ainsi une lecture ulterieure retournera a nouveau les
memes donnees.

L'option
.B MSG_WAITALL
demande que l'operation de lecture soit bloquee jusqu'a ce que
la requete complete soit satisfaite. Toutefois la lecture peut 
retourner quand meme moins de donnees que prevu si un signal
est recu, une erreur ou une deconnexion se produit.

l'appel
.B recvmsg
utilise une structure
.I msghdr
pour minimiser le nombre de parametres a fournir directement. Cette
structure a la forme suivante, definie 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
specifient l'adresse destination si la socket n'est pas connectee,
.I msg_name
peut etre un pointeur nul si le nom n'est pas necessaire.
.I Msg_iov
et
.I msg_iovlen
decrivent les buffers de reception comme decrit dans
.BR readv (2).
.IR Msg_control ,
de longueur
.IR msg_controllen ,
pointe sur un buffer utilise pour les autres messages relatifs au protocole,
ou a d'autres donnees 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 etre informe des changements du
flux de donnees avec XNS/SPP, 
ou pour obtenir des donnees d'identification en demandant un recvmsg
sans buffer immediatement apres l'appel de
.B accept
avec ISO.

Les descripteurs de fichiers annexes sont desormais passes
en tant que donnees 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
indiqe une fin d'enregistrement, les donnees recues terminent un
enregistrement (utilise generalement avec les sockets du type
.BR SOCK_SEQPACKET ).
.B MSG_TRUNC
indique que la portion finale du datagramme a ete abandonnee car le
datagramme etait trop long pour le buffer fourni.
.B MSG_CTRUNC
indique que des donnees de controle ont ete abandonnees a cause d'un 
manque de place dans le buffer de donnees annexes.
.B MSG_OOB
indique que des donnes hors-bande ont ete recues.

.SH "VALEUR RENVOYEE"
Ces fonctions
renvoient le nombre d'octets recus si elles reussissent, 
ou \-1 en cas d'echec, 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 avec un protocole oriente connexion et
n'a pas encore ete connectee (voir
.BR connect (2)
et
.BR accept (2)).
.TP
.B ENOTSOCK
L'argument
.I s
ne correspond pas a une socket.
.TP
.B 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.
.TP
.B EINTR
Un signal a interrompu la lecture avant que des donnees soient 
disponibles.
.TP
.B EFAULT
Un buffer pointe en dehors de l'espace d'adressage accessible.
.SH CONFORMITE
4.4 BSD (ces fonctions sont apparus dans BSD 4.2).
.SH "VOIR AUSSI"
.BR fcntl "(2), " read "(2), " select "(2), " getsockopt "(2), " socket (2)