Provided by:
manpages-es_1.55-10_all 
NOMBRE
recv, recvfrom, recvmsg - reciben un mensaje desde un conector
SINOPSIS
#include <sys/types.h>
#include <sys/socket.h>
ssize_t recv(int s, void *buf, size_t lon, int flags);
ssize_t recvfrom(int s, void *buf, size_t lon, int flags, struct
sockaddr *desde, socklen_t *londesde);
ssize_t recvmsg(int s, struct msghdr *msg, int flags);
DESCRIPCI'ON
Las llamadas recvfrom y recvmsg se emplean para recibir mensajes desde
un conector (``socket''), y pueden utilizarse para recibir datos de un
conector sea orientado a conexion o no.
Si desde no es NULL y el conector no es orientado a conexion, la
direccion fuente del mensaje se llena. El argumento londesde es un
parametro por referencia, inicializado al tamano del bufer asociado con
desde, y modificado cuando la funcion regresa para indicar el tamano
real de la direccion guardada ahi.
La llamada a recv se utiliza normalmente solo en un conector conectado
(vea connect(2)) y es identica a recvfrom con un parametro desde con
valor NULL.
Las tres rutinas devuelven la longitud del mensaje cuando terminan
bien. Si un mensaje es demasiado largo como para caber en el bufer
suministrado, los bytes que sobran pueden descartarse dependiendo del
tipo de conector del que se reciba el mensaje (vea socket(2)).
Si no hay mensajes disponibles en el conector, las llamadas de
recepcion esperan que llegue un mensaje, a menos que el conector sea no
bloqueante (vea fcntl(2)) en cuyo caso se devuelve el valor -1 y la
variable externa errno toma el valor EAGAIN. Las llamadas de recepcion
devuelven normalmente cualquier dato disponible, hasta la cantidad
pedida, en vez de esperar la recepcion de la cantidad pedida completa.
Las llamadas select(2) o poll(2) pueden emplearse para determinar
cuando llegan mas datos.
El argumento flags de una llamada a recv se forma aplicando el operador
de bits O-logico a uno o mas de los valores siguientes:
MSG_OOB
Esta opcion pide la recepcion de datos fuera-de-banda que no se
recibirian en el flujo de datos normal. Algunos protocolos ponen
datos despachados con prontitud en la cabeza de la cola de datos
normales, y asi, esta opcion no puede emplearse con tales
protocolos.
MSG_PEEK
Esta opcion hace que la operacion de recepcion devuelva datos
del principio de la cola de recepcion sin quitarlos de alli.
Asi, una proxima llamada de recepcion devolvera los mismos
datos.
MSG_WAITALL
Esta opcion hace que la operacion se bloquee hasta que se
satisfaga la peticion completamente. Sin embargo, la llamada
puede aun devolver menos datos de los pedidos si se captura una
senal, si ocurre un error o una desconexion, o si los proximos
datos que se van a recibir son de un tipo diferente del que se
ha devuelto.
MSG_NOSIGNAL
Esta opcion desactiva el que se produzca una senal SIGPIPE sobre
los conectores orientados a conexion cuando el otro extremo
desaparece.
MSG_TRUNC
Devuelve la longitud real del paquete, incluso cuando es mas
largo que el bufer pasado. Esta opcion solo es valida para
conectores de paquete.
MSG_ERRQUEUE
Esta opcion 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
IPv4 este es IP_RECVERR). El usuario debe proporciona un buffer
de tamano suficiente. Vea cmsg(3) y ip(7) para obtener mas
informacion. El contenido util del paquete original que provoco
el error se pasa como datos normales a traves de msg_iovec. La
direccion original de destino del datagrama que provoco el error
se pasa a traves de msg_name.
Para errores locales, no se pasa ninguna direccion (esto puede
comprobarse con el miembro cmsg_len de cmsghdr). Para los
errores recibidos, se asigna MSG_ERRQUEUE a msghdr. Despues de
que se haya pasado un error, el error de conector pendiente se
regenera basandose en el siguiente error encolado y se pasara en
la siguiente operacion de conectores.
El error se suministra en una estructura sock_extended_err:
#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
{
u_int32_t ee_errno; /* numero de error */
u_int8_t ee_origin; /* origen del error */
u_int8_t ee_type; /* tipo */
u_int8_t ee_code; /* codigo */
u_int8_t ee_pad;
u_int32_t ee_info; /* informacion adicional */
u_int32_t ee_data; /* otros datos */
/* Pueden ir mas datos a continuacion .*/
};
struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);
ee_errno contiene el numero errno del error encolado. ee_origin
es el codigo del origen en donde se ha originado el error. Los
otros campos son especificos del protocolo. La macro
SOCK_EE_OFFENDER devuelve un puntero a la direccion del objeto
de red desde donde se ha originado el error dando un puntero al
mensaje auxiliar. Si esta direccion se desconoce, el miembro
sa_family de sockaddr contiene AF_UNSPEC y los otros campos de
sockaddr quedan indefinidos. El contenido util del paquete que
ha producido el error se pasa como datos normales.
Para los errores locales no se pasa ninguna direccion (esto se
puede comprobar con el miembro cmsg_len de cmsghdr). Para los
errores recibidos, se asigna MSG_ERRQUEUE a msghdr. Despues de
que se haya pasado un error, el error de conector pendiente se
regenera basandose en el siguiente error encolado y se pasara en
la siguiente operacion de conectores.
La llamada recvmsg utiliza una estructura msghdr para minimizar el
numero de parametros suministrados directamente. Esta estructura tiene
la forma siguiente, segun se define en <sys/socket.h>:
struct msghdr {
void * msg_name; /* direccion opcional */
socklen_t msg_namelen; /* tamano de la direccion */
struct iovec * msg_iov; /* vector dispersar/agrupar */
size_t msg_iovlen; /* no de elementos en msg_iov */
void * msg_control; /* datos auxiliares, ver mas abajo */
socklen_t msg_controllen; /* long buffer datos auxiliares */
int msg_flags; /* opciones en mensaje recibido */
};
Aqui msg_name y msg_namelen especifican la direccion de origen si el
conector esta desconectado; msg_name puede darse como un puntero nulo
si no se desean o requieren nombres. Los campos msg_iov y msg_iovlen
describen localizaciones dispersar/agrupar, como se discute en
readv(2). El campo msg_control, que tiene de longitud msg_controllen,
apunta a un bufer para otros mensajes relacionados con control de
protocolo o para datos auxiliares diversos. Cuando se llama a recvmsg,
msg_controllen debe contener la longitud del buffer disponible en
msg_control; a la vuelta de una llamada con exito contendra la longitud
de la secuencia de mensajes de control.
Los mensajes son de la forma:
struct cmsghdr {
socklen_t cmsg_len; /* No de byte de datos, incluye cab. */
int cmsg_level; /* protocolo originante */
int cmsg_type; /* tipo especifico del protocolo */
/* seguido por
u_char cmsg_data[]; */
};
Los datos auxiliares solo deberian ser accedidos mediante las macros
definidas en cmsg(3).
Como ejemplo, Linux usa este mecanismo de datos auxiliares para pasar
errores ampliados, opciones IP o descriptores de fichero mediante
conectores Unix.
El contenido del campo msg_flags en msghdr se establece cuando
recvmsg() regresa. Puede contener numerosas opciones:
MSG_EOR
indica fin-de-registro; los datos devueltos completaron un
registro (generalmente empleado con conectores del tipo
SOCK_SEQPACKET).
MSG_TRUNC
indica que la porcion trasera de un datagrama ha sido descartada
porque el datagrama era mas grande que el bufer suministrado.
MSG_CTRUNC
indica que algun dato de control ha sido descartado debido a la
falta de espacio en el bufer para datos auxiliares.
MSG_OOB
se devuelve para indicar que se han recibido datos despachados
prontamente o fuera-de-banda.
MSG_ERRQUEUE
indica que no se ha recibido ningun dato sino un error ampliado
de la cola de errores de conectores.
MSG_DONTWAIT
Permite operaciones no-bloqueantes; si la operacion se
bloqueara, se devolveria EAGAIN (tambien se puede conseguir esto
usando la opcion O_NONBLOCK con F_SETFL fcntl(2)).
VALOR DEVUELTO
Estas llamadas devuelven el numero de bytes recibidos, o bien -1 en
caso de que ocurriera un error.
ERRORES
Estos son algunos errores estandares generados por la capa de
conectores. Los modulos de los protocolos subyacentes pueden generar y
devolver errores adicionales. Consulte sus paginas de manual.
EBADF El argumento s es un descriptor invalido.
ECONNREFUSED
Un host remoto no permite la conexion de red (normalmente porque
no esta ejecutando el servicio solicitado).
ENOTCONN
El conector esta asociado con un protocolo orientado a la
conexion y no ha sido conectado (vea connect(2) y accept(2)).
ENOTSOCK
El argumento s no se refiere a un conector.
EAGAIN El conector esta marcado como no-bloqueante, y la operacion de
recepcion produciria un bloqueo, o se ha puesto un limite de
tiempo en la recepcion, que ha expirado antes de que se
recibieran datos.
EINTR La recepcion ha sido interrumpida por la llegada de una senal
antes de que hubiera algun dato disponible.
EFAULT El puntero a bufer de recepcion (o punteros) apunta afuera del
espacio de direcciones del proceso.
EINVAL Se ha pasado un argumento invalido.
CONFORME A
4.4BSD (estas funciones aparecieron por primera vez en 4.2BSD).
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 flags es un `int' en BSD 4.* pero es un `unsigned
int' en libc4 y libc5. El argumento lon es un `int' en BSD 4.* pero es
un `size_t' en libc4 y libc5. El argumento londesde es un `int' en BSD
4.*, libc4 y libc5. El actual `socklen_t *' fue inventado por POSIX.
Vea tambien accept(2).
V'EASE TAMBI'EN
fcntl(2), read(2), select(2), getsockopt(2), socket(2), cmsg(3)
Pagina man de Linux 31 diciembre 2002 RECV(2)