.\" 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>
.\" Modified Tue Oct 22 17:45:19 1996 by Eric S. Raymond <esr@thyrsus.com>
.\" Translated into Spanish Sat Jan 24 1998 by Gerardo Aburruzaga
.\" Garca <gerardo.aburruzaga@uca.es>
.\"
.TH RECV 2 "24 Enero 1998" "BSD" "Manual del Programador de Linux"
.SH NOMBRE
recv, recvfrom, recvmsg \- reciben un mensaje desde un zcalo
.SH SINOPSIS
.B #include <sys/types.h>
.br
.B #include <sys/socket.h>
.sp 2
.BI "int recv(int " s ", void *" buf ", int " lon ", unsigned int " flags );
.sp
.BI "int recvfrom(int " s ", void *" buf ", int " lon ", unsigned int " flags
.BI ", struct sockaddr *" desde ", int *" londesde );
.sp
.BI "int recvmsg(int " s ", struct msghdr *" msg ", unsigned int " flags );
.SH DESCRIPCIN
Las primitivas
.B recvfrom
y
.B recvmsg
se emplean para recibir mensajes desde un zcalo (``socket''), y
pueden utilizarse para recibir datos de un zcalo sea orientado a
conexin o no.

Si
.I desde
no es nulo, y el zcalo no es orientado a conexin, la direccin
fuente del mensaje se llena.
.I Londesde
es un parmetro por referencia, inicializado al tamao del bfer
asociado con 
.IR desde ,
y modificado cuando la funcin regresa para indicar el tamao real de
la direccin guardada ah.

La llamada a
.B recv
se utiliza normalmente slo en un zcalo
.I conectado
(vea
.BR connect (2))
y es idntica a
.B recvfrom
con un parmetro
.I desde
nulo. Como es redundante, puede que en futuras distribuciones no est
mantenida. 

Las tres rutinas devuelven la longitud del mensaje cuando terminan bien.
Si un mensaje es demasiado largo como para caber en el bfer
suministrado, los bytes que sobran pueden descartarse dependiendo del
tipo de zcalo del que se reciba el mensaje (vea
.BR socket (2)).

Si no hay mensajes disponibles en el zcalo, la llamada de recepcin
espera que llegue un mensaje, a menos que el zcalo sea no bloqueante (vea
.BR fcntl (2))
en cuyo caso se devuelve el valor \-1 y la variable externa
.I errno
toma el valor
.BR EWOULDBLOCK .
Las llamadas de recepcin devuelven normalmente cualquier dato
disponible, hasta la cantidad pedida, en vez de esperar la recepcin
de la cantidad pedida completa; este comportamiento se ve afectado por
las opciones del nivel de zcalos
.B SO_RCVLOWAT
y
.B SO_RCVTIMEO
descritas en
.BR getsockopt (2).

La llamada
.BR select (2)
puede emplearse para determinar cundo llegan ms datos.

El argumento
.I flags
de una llamada a recv se forma aplicando el operador de bits
.IR OR
a uno o ms de los valores:
.TP 0.8i
.TP
MSG_OOB
procesar datos fuera-de-banda
.TP
MSG_PEEK
mirar el mensaje entrante
.\" peek at incoming message
.TP
MSG_WAITALL
esperar a que se complete la peticin u ocurra un error

La opcin
.B MSG_OOB
pide la recepcin de datos fuera-de-banda que no se recibiran en el
flujo de datos normal. Algunos protocolos ponen datos despachados con
prontitud en la cabeza de la cola de datos normales, y as, esta
opcin no puede emplearse con tales protocolos.

La opcin
.B MSG_PEEK
hace que la operacin de recepcin devuelva datos del principio de la
cola de recepcin sin quitarlos de all. As, una prxima llamada de
recepcin devolver los mismos datos. La opcin 
.B MSG_WAITALL
pide que la operacin se bloquee hasta que se satisfaga la peticin
completamente. Sin embargo, la llamada puede an devolver menos datos
de los pedidos si se captura una seal, si ocurre un error o una
desconexin, o si los prximos datos que se van a recibir son de un
tipo diferente del que se ha devuelto.

La llamada
.B recvmsg
utiliza una estructura
.I msghdr
para minimizar el nmero de parmetros suministrados
directamente. Esta estructura tiene la forma siguiente, segn se
define en
.IR sys/socket.h :

.RS
.nf
struct msghdr {
	caddr_t	msg_name;	/* direccin opcional */
	u_int	msg_namelen;	/* tamao de direccin */
	struct	iovec *msg_iov;	/* vector disperso/reunido */
	u_int	msg_iovlen;	/* N de elementos en msg_iov */
	caddr_t	msg_control;	/* datos auxiliares, vea abajo */
	u_int	msg_controllen; /* long. bfer datos auxiliares */
	int	msg_flags;	/* opciones en mensaje recibido */
};
.fi
.RE

Aqu
.I msg_name
y
.I msg_namelen
especifican la direccin de destino si el zcalo est desconectado;
.I msg_name
puede darse como un puntero nulo si no se desean o requieren nombres.
.I Msg_iov
y
.I msg_iovlen
describen localizaciones recogidas dispersas, como se discute en
.BR readv (2).
.IR Msg_control ,
que tiene de longitud
.IR msg_controllen ,
apunta a un bfer para otros mensajes relacionados con control de
protocolo o para otros datos auxiliares diversos. Los mensajes son de
la forma:

.RS
.nf
struct cmsghdr {
	u_int	cmsg_len;	/* N de byte de datos, incluye cab. */
	int	cmsg_level;	/* protocolo originante */
	int	cmsg_type;	/* tipo especfico del protocolo */
/* seguido por
	u_char	cmsg_data[]; */
};
.fi
.RE

Como ejemplo, uno podra usar esto para saber los cambios en el flujo
de datos en XNS/SSP, o en ISO, para obtener datos de
peticin-de-conexin-de-usuario mediante la llamada a recvmsg sin
proporcionar un bfer de datos, inmediatamente tras una llamada a
\fBaccepct\fP. 

Los descriptores de ficheros abiertos se pasan ya como datos
auxiliares para zcalos de dominio \fBAF_UNIX\fP, con
.I cmsg_level
puesto a
.B SOL_SOCKET
y
.I cmsg_type
puesto a
.BR SCM_RIGHTS .

El campo
.I msg_flags
toma un valor al regresar dependiendo del mensaje recibido.
.B MSG_EOR
indica fin-de-registro; los datos devueltos completaron un registro
(generalmente empleado con zcalos del tipo
.BR SOCK_SEQPACKET ).
.B MSG_TRUNC
indica que la porcin trasera de un datagrama ha sido descartada
porque el datagrama era ms grande que el bfer suministrado.
.B MSG_CTRUNC
indica que algn dato de control ha sido descartado debido a la falta
de espacio en el bfer para datos auxiliares.
.B MSG_OOB
se devuelve para indicar que se han recibido datos despachados
prontamente o fuera-de-banda.

.SH "VALORES DEVUELTOS"
Estas llamadas devuelven el nmero de bytes recibidos, o bien \-1
en caso de que ocurriera un error.
.SH ERRORES
.TP 0.8i
.B EBADF
El argumento
.I s
es un descriptor invlido.
.TP
.B ENOTCONN
El zcalo est asociado con un protocolo orientado a la conexin y no
ha sido conectado (vea
.BR connect (2)
y
.BR accept (2)).
.TP
.B ENOTSOCK
El argumento
.I s
no se refiere a un zcalo.
.TP
.B EWOULDBLOCK
El zcalo est marcado como no-bloqueante, y la operacin de recepcin
producira un bloqueo, o se ha puesto un lmite de tiempo en la
recepcin, que ha expirado antes de que se recibieran datos.
.TP
.B EINTR
La recepcin ha sido interrumpida por la llegada de una seal antes de
que hubiera algn dato disponible.
.TP
.B EFAULT
El puntero a bfer de recepcin (o punteros) apunta afuera del espacio
de direcciones del proceso.
.SH "CONFORME CON"
4.4BSD (estas funciones aparecieron por primera vez en 4.2BSD).
.SH "VASE TAMBIN"
.BR fcntl "(2), " read "(2), " select "(2), " getsockopt "(2), " socket (2)