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'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)