Provided by: manpages-es_1.55-10_all bug

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)