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)