Provided by: manpages-es_1.55-10_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)