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

NOMBRE

       getaddrinfo - traducción de servicios y direcciones de red

SINOPSIS

       #include <sys/types.h>
       #include <sys/socket.h>
       #include <netdb.h>

       int getaddrinfo(const char *node, const char *service,
                       const struct addrinfo *hints,
                       struct addrinfo **res);

       void freeaddrinfo(struct addrinfo *res);

       const char *gai_strerror(int errcode);

DESCRIPCIÓN

       La  función  getaddrinfo(3)  combina  la funcionalidad provista por las
       funciones getipnodebyname(3), getipnodebyaddr(3),  getservbyname(3),  y
       getservbyport(3)   en  una  única  interfaz.   La  función  hilo-seguro
       getaddrinfo(3) crea una o más estructuras de dirección  de  socket  que
       pueden  ser utilizadas por las llamadas al sistema bind(2) y connect(2)
       para crear un socket cliente o servidor.

       La función getaddrinfo(3) no se limita a la creación de estructuras  de
       dirección  de  socket  IPv4;  puede  crear  estructuras de dirección de
       socket IPv6 si el soporte para IPv6 está disponible.  Estas estructuras
       de  dirección  de  socket  pueden ser usadas directamente por bind(2) o
       connect(2), para preparar un socket cliente o servidor.

       La estructura addrinfo usada por esta función contiene  los  siguientes
       miembros:

       struct addrinfo {
           int     ai_flags;
           int     ai_family;
           int     ai_socktype;
           int     ai_protocol;
           size_t  ai_addrlen;
           struct sockaddr *ai_addr;
           char   *ai_canonname;
           struct addrinfo *ai_next;
       };

       getaddrinfo(3)  modifica  res  para  que  apunte  a  la  lista dinámica
       enlazada de estructuras addrinfo , enlazada  por  el  miembro  ai_next.
       Hay muchas razones por las que la lista enlazada puede tener más de una
       estructura addrinfo , incluyendo: si el host tiene más de una dirección
       IP;  o  si el mismo servicio está disponible desde múltiples protocolos
       de socket (uno  desde  una  dirección  SOCK_STREAM  y  otro  desde  una
       dirección SOCK_DGRAM , por ejemplo).

       Los  miembros  ai_family,  ai_socktype,  y  ai_protocol tienen el mismo
       significado  que  los  correspondientes  parámetros   de   la   llamada
       socket(2).  La función getaddrinfo(3) devuelve direcciones de socket en
       la familia de direcciones IPv4 o IPv6, (ai_family contendrá  PF_INET  o
       PF_INET6).

       El  parámetro hints especifica el tipo de socket o protocolo preferido.
       Un valor de NULL en hints especifica que cualquier dirección de  red  o
       protocolo es aceptable.  Si este parámetro es distinto de NULL apunta a
       una  estructura  addrinfo  cuyos  miembros  ai_family,  ai_socktype,  y
       ai_protocol  especifican  el  tipo  de  socket preferido.  PF_UNSPEC en
       ai_family especifica cualquier familia de protocolos (bien IPv4 o IPv6,
       por  ejemplo).   Un  valor de 0 en ai_socktype o ai_protocol especifica
       que cualquier tipo de socket o  protocolo  es  aceptable  también.   El
       miembro  ai_flags especifica opciones adicionales, definidas más abajo.
       Se pueden especificar múltiples opciones mediante un OR lógica de todas
       ellas.  Todos los demás miembros en el parámetro hints deben contener o
       bien 0, un puntero null.

       El parámetro node o service , pero no ambos,  pueden  ser  NULL.   node
       especifica o bien una dirección de red numérica (en formato decimal con
       puntos para IPv4, format hexadecimal para IPv6) o un  nombre  de  host,
       cuyas  direcciones  de  red  son  buscadas  y resueltas.  Si el miembro
       ai_flags en el parámetro hints contiene  la  opción  AI_NUMERICHOST  el
       parámetro  node  debe  ser  una  dirección  de red numérica.  La opción
       AI_NUMERICHOST  suprime   cualquier   búsqueda   larga   potencial   de
       direcciones de host.

       La  función  getaddrinfo(3)  crea  una  lista  enlazada  de estructuras
       addrinfo  ,  una  para  cada  dirección  de  red  sujeta  a   cualquier
       restricción  impuesta por el parámetro hints.  ai_canonname se modifica
       para que apunte al nombre  oficial  del  host,  si  ai_flags  en  hints
       incluye  la opción AI_CANONNAME.  ai_family, ai_socktype, y ai_protocol
       especifican los parámetros  de  creación  del  socket.   Se  guarda  un
       puntero  a la dirección de socket en el miembro ai_addr , y la longitud
       de la dirección de socket, en bytes, se deja en el miembro  ai_addrlen.

       Si  node  es  distinto  de NULL, la dirección de red en cada estructura
       socket es inicializada según la opción AI_PASSIVE , que es activada  en
       el  miembro  ai_flags del parámetro hints.  La dirección de red en cada
       estructura socket se quedará sin definir si la opción  AI_PASSIVE  está
       activa.   Ésto  es  usado  por  aplicaciones  servidoras,  que intentan
       aceptar conexiones del cliente en cualquier dirección  de  red.   A  la
       dirección de red se le asignará la dirección de la interfaz de loopback
       si la opción AI_PASSIVE no está activa.  Ésto es usado por aplicaciones
       cliente,  que  intentan  conectar  con servidores que se ejecutan en el
       mismo host.

       service establece el número de puerto en la dirección de  red  de  cada
       estructura  socket.   Si  service es NULL el número de puerto se dejará
       sin inicializar.

       La función freeaddrinfo(3) libera la memoria  que  fue  asignada  a  la
       lista dinámica enlazada res.

VALOR DEVUELTO

       getaddrinfo(3)  devuelve  0  si  tiene  éxito,  o uno de los siguientes
       códigos de error:

       EAI_FAMILY
              La familia  de  direcciones  solicitada  no  está  soportada  en
              absoluto.

       EAI_SOCKTYPE
              El tipo de socket solicitado no está soportado en absoluto.

       EAI_BADFLAGS
              ai_flags contiene opciones no válidas.

       EAI_NONAME
              El nodo node o el servicio service no son conocidos.  Este error
              también se devuelve si tanto node como service son NULL.

       EAI_SERVICE
              El servicio solicitado no está disponible para el tipo de socket
              solicitado.   Puede  estar  disponible  a través de otro tipo de
              socket.

       EAI_ADDRFAMILY
              El host especificado no tiene ninguna dirección  de  red  en  la
              familia de direcciones especificada.

       EAI_NODATA
              El  host especificado existe, pero no tiene ninguna dirección de
              red definida.

       EAI_MEMORY
              Memoria insuficiente.

       EAI_FAIL
              El  servidor  de  nombres  devolvió  una  indicación  de   fallo
              permanente.

       EAI_AGAIN
              El   servidor  de  nombres  devolvió  una  indicación  de  fallo
              temporal.  Pruebe más tarde.

       EAI_SYSTEM
              Otro error de sistema, compruebe errno para más detalles.

       La función gai_strerror(3) transforma estos  códigos  de  erro  en  una
       cadena comprensible, adecuada para el informe de errores.

VÉASE TAMBIÉN

       getipnodebyname(3), getipnodebyaddr(3)