Ubuntu Manpage: recv, recvfrom, recvmsg - reciben un mensaje desde un conector

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ÓN

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
conexión o no.

Si desde no es NULL y el conector no es orientado a conexión, la dirección fuente del
mensaje se llena. El argumento londesde es un parámetro por referencia, inicializado al
tamaño del búfer asociado con desde, y modificado cuando la función regresa para indicar
el tamaño real de la dirección guardada ahí.

La llamada a recv se utiliza normalmente sólo en un conector conectado (vea connect(2)) y
es idéntica a recvfrom con un parámetro 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 búfer 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 recepción 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
recepción devuelven normalmente cualquier dato disponible, hasta la cantidad pedida, en
vez de esperar la recepción de la cantidad pedida completa.

Las llamadas select(2) o poll(2) pueden emplearse para determinar cuándo llegan más datos.

El argumento flags de una llamada a recv se forma aplicando el operador de bits O-lógico a
uno o más de los valores siguientes:

MSG_OOB
Esta opción pide la recepción de datos fuera-de-banda que no se recibirían 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 opción no puede emplearse con
tales protocolos.

MSG_PEEK
Esta opción hace que la operación de recepción devuelva datos del principio de la
cola de recepción sin quitarlos de allí. Así, una próxima llamada de recepción
devolverá los mismos datos.

MSG_WAITALL
Esta opción hace que la operación se bloquee hasta que se satisfaga la petición
completamente. Sin embargo, la llamada puede aún devolver menos datos de los
pedidos si se captura una señal, si ocurre un error o una desconexión, o si los
próximos datos que se van a recibir son de un tipo diferente del que se ha
devuelto.

MSG_NOSIGNAL
Esta opción desactiva el que se produzca una señal SIGPIPE sobre los conectores
orientados a conexión cuando el otro extremo desaparece.

MSG_TRUNC
Devuelve la longitud real del paquete, incluso cuando es más largo que el búfer
pasado. Esta opción sólo es válida para conectores de paquete.

MSG_ERRQUEUE
Esta opción 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 éste es IP_RECVERR). El usuario debe
proporciona un buffer de tamaño suficiente. Vea cmsg(3) y ip(7) para obtener más
información. El contenido útil del paquete original que provocó el error se pasa
como datos normales a través de msg_iovec. La dirección original de destino del
datagrama que provocó el error se pasa a través de msg_name.

Para errores locales, no se pasa ninguna dirección (ésto puede comprobarse con el
miembro cmsg_len de cmsghdr). Para los errores recibidos, se asigna MSG_ERRQUEUE a
msghdr. Después de que se haya pasado un error, el error de conector pendiente se
regenera basándose en el siguiente error encolado y se pasará en la siguiente
operación 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; /* número de error */
u_int8_t ee_origin; /* origen del error */
u_int8_t ee_type; /* tipo */
u_int8_t ee_code; /* código */
u_int8_t ee_pad;
u_int32_t ee_info; /* información adicional */
u_int32_t ee_data; /* otros datos */
/* Pueden ir más datos a continuación .*/
};

struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);

ee_errno contiene el número errno del error encolado. ee_origin es el código del
origen en donde se ha originado el error. Los otros campos son específicos del
protocolo. La macro SOCK_EE_OFFENDER devuelve un puntero a la dirección del objeto
de red desde donde se ha originado el error dando un puntero al mensaje auxiliar.
Si esta dirección se desconoce, el miembro sa_family de sockaddr contiene AF_UNSPEC
y los otros campos de sockaddr quedan indefinidos. El contenido útil del paquete
que ha producido el error se pasa como datos normales.

Para los errores locales no se pasa ninguna dirección (esto se puede comprobar con
el miembro cmsg_len de cmsghdr). Para los errores recibidos, se asigna
MSG_ERRQUEUE a msghdr. Después de que se haya pasado un error, el error de
conector pendiente se regenera basándose en el siguiente error encolado y se pasará
en la siguiente operación de conectores.

La llamada recvmsg utiliza una estructura msghdr para minimizar el número de parámetros
suministrados directamente. Esta estructura tiene la forma siguiente, según se define en
<sys/socket.h>:

struct msghdr {
void * msg_name; /* dirección opcional */
socklen_t msg_namelen; /* tamaño de la dirección */
struct iovec * msg_iov; /* vector dispersar/agrupar */
size_t msg_iovlen; /* nº de elementos en msg_iov */
void * msg_control; /* datos auxiliares, ver más abajo */
socklen_t msg_controllen; /* long buffer datos auxiliares */
int msg_flags; /* opciones en mensaje recibido */
};

Aquí msg_name y msg_namelen especifican la dirección de origen si el conector está
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 búfer 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 éxito contendrá la
longitud de la secuencia de mensajes de control.

Los mensajes son de la forma:

struct cmsghdr {
socklen_t cmsg_len; /* Nº de byte de datos, incluye cab. */
int cmsg_level; /* protocolo originante */
int cmsg_type; /* tipo específico del protocolo */
/* seguido por
u_char cmsg_data[]; */
};

Los datos auxiliares sólo deberían 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 porción trasera de un datagrama ha sido descartada porque el
datagrama era más grande que el búfer suministrado.

MSG_CTRUNC
indica que algún dato de control ha sido descartado debido a la falta de espacio en
el búfer 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 ningún dato sino un error ampliado de la cola de
errores de conectores.

MSG_DONTWAIT
Permite operaciones no-bloqueantes; si la operación se bloqueara, se devolvería
EAGAIN (también se puede conseguir ésto usando la opción O_NONBLOCK con F_SETFL
fcntl(2)).

VALOR DEVUELTO

       Estas llamadas devuelven el número de bytes recibidos, o bien -1 en caso de que  ocurriera
       un error.

ERRORES

       Estos  son algunos errores estándares generados por la capa de conectores.  Los modulos de
       los protocolos subyacentes pueden generar y devolver  errores  adicionales.  Consulte  sus
       páginas de manual.

       EBADF  El argumento s es un descriptor inválido.

       ECONNREFUSED
              Un host remoto no permite la conexión de red (normalmente porque no está ejecutando
              el servicio solicitado).

       ENOTCONN
              El conector está asociado con un protocolo orientado a la conexión  y  no  ha  sido
              conectado (vea connect(2) y accept(2)).

       ENOTSOCK
              El argumento s no se refiere a un conector.

       EAGAIN El conector está marcado como no-bloqueante, y la operación de recepción produciría
              un bloqueo, o se ha puesto un límite de tiempo en la  recepción,  que  ha  expirado
              antes de que se recibieran datos.

       EINTR  La  recepción ha sido interrumpida por la llegada de una señal antes de que hubiera
              algún dato disponible.

       EFAULT El puntero a  búfer  de  recepción  (o  punteros)  apunta  afuera  del  espacio  de
              direcciones del proceso.

       EINVAL Se ha pasado un argumento inválido.

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 también accept(2).

VÉASE TAMBIÉN

       fcntl(2), read(2), select(2), getsockopt(2), socket(2), cmsg(3)