.\" 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.
.\"
.\"     $Id: recv.2,v 1.3 1999/05/13 11:33:38 freitag Exp $
.\"
.\" 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>
.\" Modified 1998,1999 by Andi Kleen
.\" Translation revised Tue Apr  6 1999 by Juan Piernas <piernas@ditec.um.es>
.\" Translation revised Sun Jun 27 1999 by Juan Piernas <piernas@ditec.um.es>
.\"
.TH RECV 2 "Abril 1999" "Pgina man de Linux" "Manual del Programador de Linux"
.SH NOMBRE
recv, recvfrom, recvmsg \- reciben un mensaje desde un conector
.SH SINOPSIS
.B #include <sys/types.h>
.br
.B #include <sys/socket.h>
.sp
.BI "int recv(int " s ", void *" buf ", size_t " lon ", int " flags );
.sp
.BI "int recvfrom(int " s ", void *" buf ", size_t " lon ", int " flags ","
.BI "struct sockaddr *" desde ", socklen_t *" londesde );
.sp
.BI "int recvmsg(int " s ", struct msghdr *" msg ", int " flags );
.SH DESCRIPCIN
Las llamadas
.B recvfrom
y
.B recvmsg
se emplean para recibir mensajes desde un conector (``socket''), y
pueden utilizarse para recibir datos de un conector sea orientado a
conexin o no.
.PP
Si
.I desde
no es NULL y el conector no es orientado a conexin, la direccin
fuente del mensaje se llena.
El argumento
.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.
.PP
La llamada a
.B recv
se utiliza normalmente slo en un conector
.I conectado
(vea
.BR connect (2))
y es idntica a
.B recvfrom
con un parmetro
.I desde
con valor NULL.
.PP
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 conector del que se reciba el mensaje (vea
.BR socket (2)).
.PP
Si no hay mensajes disponibles en el conector, las llamadas de recepcin
esperan que llegue un mensaje, a menos que el conector 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 EAGAIN .
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 conectores
.B SO_RCVLOWAT
y
.B SO_RCVTIMEO
descritas en
.BR socket (7).
.PP
Las llamadas
.BR select (2)
o
.BR poll (2)
pueden emplearse para determinar cundo llegan ms datos.
.PP
El argumento
.I flags
de una llamada a recv se forma aplicando el operador de bits
.IR O -lgico
a uno o ms de los valores siguientes:
.TP
.B MSG_OOB
Esta opcin 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.
.TP
.B MSG_PEEK
Esta opcin 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.
.TP
.B MSG_WAITALL
Esta opcin hace 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.
.TP
.B MSG_ERRQUEUE
Recibir paquete de la cola de errores
.TP
.B MSG_NOSIGNAL
Esta opcin desactiva el que se produzca una seal
.B SIGPIPE
sobre los conectores orientados a conexin cuando el otro extremo desaparece.
.TP
.B MSG_ERRQUEUE
Esta opcin indica que los errores encolados deben recibirse desde la cola
de errores de conectores.
El error se pasa en un mensaje auxiliar con un tipo dependiente del protocolo
(para IP ste es
.BR IP_RECVERR ).
El error se suministra en una estructura
.BR sock_extended_err :
.IP
.RS
.ne 18
.nf
.ta 4n 20n 32n
.\" XXX switch to standard types
#define SO_EE_ORIGIN_NONE     0
#define SO_EE_ORIGIN_LOCAL    1
#define SO_EE_ORIGIN_ICMP     2
#define SO_EE_ORIGIN_ICMP6    3

struct sock_extended_err
{
      __u32   ee_errno;       /* nmero de error */
      __u8    ee_origin;      /* origen del error */
      __u8    ee_type;        /* tipo */
      __u8    ee_code;        /* cdigo */
      __u8    ee_pad;
      __u32   ee_info;        /* informacin adicional */
      __u32   ee_data;        /* otros datos */
};

struct sockaddr *SOCK_EE_OFFENDER(struct sock_extended_err *);
.ta
.fi
.RE
.IP
.B ee_errno
contiene el nmero errno del error encolado.
.B ee_origin
es el cdigo del origen en donde se ha originado el error.
Los otros campos son especficos del protocolo.
.B SOCK_EE_OFFENDER
devuelve un puntero a la direccin del objeto de red desde donde se ha
originado el error. Si esta direccin se desconoce, el miembro
.I sa_family
de
.B sockaddr
contiene
.B AF_UNSPEC
y los otros campos de
.B sockaddr
quedan indefinidos. El contenido til del paquete que ha producido el error
se pasa como datos normales.
.IP
Para los errores locales no se pasa ninguna direccin (esto se puede
comprobar con el miembro
.I cmsg_len
de
.BR cmsghdr ).
Para los errores recibidos, se asigna
.B MSG_ERRQUEUE
a
.BR msghdr .
Despus de que se haya pasado un error, el error de conector pendiente se
regenera basndose en el siguiente error encolado y se pasar en la
siguiente operacin de conectores.
.PP
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> :
.IP
.RS
.nf
.ta 4n 17n 33n
struct msghdr {
	void	* msg_name;	/* direccin opcional */
	socklen_t	msg_namelen;	/* tamao de la direccin */
	struct iovec	* msg_iov;	/* vector dispersar/agrupar */
	size_t	msg_iovlen;	/* n de elementos en msg_iov */
	void	* msg_control;	/* datos auxiliares, ver ms abajo */
	socklen_t	msg_controllen;	/* long buffer datos auxiliares */
	int	msg_flags;	/* opciones en mensaje recibido */
};
.ta
.fi
.RE
.PP
Aqu
.I msg_name
y
.I msg_namelen
especifican la direccin de destino si el conector est desconectado;
.I msg_name
puede darse como un puntero nulo si no se desean o requieren nombres.
Los campos
.I msg_iov
y
.I msg_iovlen
describen localizaciones dispersar/agrupar, como se discute en
.BR readv (2).
El campo
.IR msg_control ,
que tiene de longitud
.IR msg_controllen ,
apunta a un bfer para otros mensajes relacionados con control de
protocolo o para datos auxiliares diversos. Cuando se llama a
.BR recvmsg ,
.I msg_controllen
debe contener la longitud del buffer disponible en
.IR msg_control ;
a la vuelta de una llamada con xito contendr la longitud de la secuencia
de mensajes de control.
.PP
Los mensajes son de la forma:
.PP
.RS
.nf
.ta 4n 16n 28n
struct cmsghdr {
	socklen_t	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[]; */
};
.ta
.fi
.RE
.PP
Los datos auxiliares slo deberan ser accedidos mediante las macros
definidas en
.BR cmsg (3).
.PP
Como ejemplo, Linux usa este mecanismo de datos auxiliares para pasar
errores ampliados, opciones IP o descriptores de fichero mediante conectores
Unix.
.PP
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 conectores 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.
.B MSG_ERRQUEUE
indica que no se ha recibido ningn dato sino un error ampliado de la cola
de errores de conectores.
.SH "VALOR DEVUELTO"
Estas llamadas devuelven el nmero de bytes recibidos, o bien \-1
en caso de que ocurriera un error.
.SH ERRORES
Estos son algunos errores estndares generados por la capa de conectores.
Los modulos de los protocolos subyacentes pueden generar y devolver errores
adicionales. Consulte sus pginas de manual.
.TP 0.8i
.B EBADF
El argumento
.I s
es un descriptor invlido.
.TP
.B ENOTCONN
El conector 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 conector.
.TP
.B EAGAIN
El conector 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.
.TP
.B EINVAL
Se ha pasado un argumento invlido.
.SH "CONFORME A"
4.4BSD (estas funciones aparecieron por primera vez en 4.2BSD).
.SH NOTA
Los prototipos datos anteriormente siguen a glibc2.
The Single Unix Specification coincide en todo excepto en que el tipo de los
valores devueltos es `ssize_t' (mientras que BSD 4.*, libc4 y libc5 tienen
`int').
El argumento
.I flags
es un `int' en BSD 4.* pero es un `unsigned int' en libc4 y libc5.
El argumento
.I lon
es un `int' en BSD 4.* pero es un `size_t' en libc4 y libc5.
El argumento
.I londesde
es un `int' en BSD 4.*, libc4 y libc5.
El actual `socklen_t *' fue inventado por POSIX.
Vea tambin
.BR accept (2).
.SH "VASE TAMBIN"
.BR fcntl (2),
.BR read (2),
.BR select (2),
.BR getsockopt (2),
.BR socket (2),
.BR cmsg (3)