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

NOMBRE

       getaddrinfo - traduccion 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'ON

       La  funcion  getaddrinfo(3)  combina  la funcionalidad provista por las
       funciones getipnodebyname(3), getipnodebyaddr(3),  getservbyname(3),  y
       getservbyport(3)   en  una  unica  interfaz.   La  funcion  hilo-seguro
       getaddrinfo(3) crea una o mas estructuras de direccion  de  socket  que
       pueden  ser utilizadas por las llamadas al sistema bind(2) y connect(2)
       para crear un socket cliente o servidor.

       La funcion getaddrinfo(3) no se limita a la creacion de estructuras  de
       direccion  de  socket  IPv4;  puede  crear  estructuras de direccion de
       socket IPv6 si el soporte para IPv6 esta disponible.  Estas estructuras
       de  direccion  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 funcion 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 dinamica
       enlazada de estructuras addrinfo , enlazada  por  el  miembro  ai_next.
       Hay muchas razones por las que la lista enlazada puede tener mas de una
       estructura addrinfo , incluyendo: si el host tiene mas de una direccion
       IP;  o  si el mismo servicio esta disponible desde multiples protocolos
       de socket (uno  desde  una  direccion  SOCK_STREAM  y  otro  desde  una
       direccion SOCK_DGRAM , por ejemplo).

       Los  miembros  ai_family,  ai_socktype,  y  ai_protocol tienen el mismo
       significado  que  los  correspondientes  parametros   de   la   llamada
       socket(2).  La funcion getaddrinfo(3) devuelve direcciones de socket en
       la familia de direcciones IPv4 o IPv6, (ai_family contendra  PF_INET  o
       PF_INET6).

       El  parametro hints especifica el tipo de socket o protocolo preferido.
       Un valor de NULL en hints especifica que cualquier direccion de  red  o
       protocolo es aceptable.  Si este parametro 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  tambien.   El
       miembro  ai_flags especifica opciones adicionales, definidas mas abajo.
       Se pueden especificar multiples opciones mediante un OR logica de todas
       ellas.  Todos los demas miembros en el parametro hints deben contener o
       bien 0, un puntero null.

       El parametro node o service , pero no ambos,  pueden  ser  NULL.   node
       especifica o bien una direccion de red numerica (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 parametro hints contiene  la  opcion  AI_NUMERICHOST  el
       parametro  node  debe  ser  una  direccion  de red numerica.  La opcion
       AI_NUMERICHOST  suprime   cualquier   busqueda   larga   potencial   de
       direcciones de host.

       La  funcion  getaddrinfo(3)  crea  una  lista  enlazada  de estructuras
       addrinfo  ,  una  para  cada  direccion  de  red  sujeta  a   cualquier
       restriccion  impuesta por el parametro hints.  ai_canonname se modifica
       para que apunte al nombre  oficial  del  host,  si  ai_flags  en  hints
       incluye  la opcion AI_CANONNAME.  ai_family, ai_socktype, y ai_protocol
       especifican los parametros  de  creacion  del  socket.   Se  guarda  un
       puntero  a la direccion de socket en el miembro ai_addr , y la longitud
       de la direccion de socket, en bytes, se deja en el miembro ai_addrlen.

       Si node es distinto de NULL, la direccion de  red  en  cada  estructura
       socket  es inicializada segun la opcion AI_PASSIVE , que es activada en
       el miembro ai_flags del parametro hints.  La direccion de red  en  cada
       estructura  socket  se quedara sin definir si la opcion AI_PASSIVE esta
       activa.  Esto  es  usado  por  aplicaciones  servidoras,  que  intentan
       aceptar  conexiones  del  cliente  en cualquier direccion de red.  A la
       direccion de red se le asignara la direccion de la interfaz de loopback
       si la opcion AI_PASSIVE no esta activa.  Esto es usado por aplicaciones
       cliente, que intentan conectar con servidores que  se  ejecutan  en  el
       mismo host.

       service  establece  el  numero de puerto en la direccion de red de cada
       estructura socket.  Si service es NULL el numero de  puerto  se  dejara
       sin inicializar.

       La  funcion  freeaddrinfo(3)  libera  la  memoria que fue asignada a la
       lista dinamica enlazada res.

VALOR DEVUELTO

       getaddrinfo(3) devuelve 0 si tiene  exito,  o  uno  de  los  siguientes
       codigos de error:

       EAI_FAMILY
              La  familia  de  direcciones  solicitada  no  esta  soportada en
              absoluto.

       EAI_SOCKTYPE
              El tipo de socket solicitado no esta soportado en absoluto.

       EAI_BADFLAGS
              ai_flags contiene opciones no validas.

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

       EAI_SERVICE
              El servicio solicitado no esta disponible para el tipo de socket
              solicitado.  Puede estar disponible a traves  de  otro  tipo  de
              socket.

       EAI_ADDRFAMILY
              El  host  especificado  no  tiene ninguna direccion de red en la
              familia de direcciones especificada.

       EAI_NODATA
              El host especificado existe, pero no tiene ninguna direccion  de
              red definida.

       EAI_MEMORY
              Memoria insuficiente.

       EAI_FAIL
              El   servidor  de  nombres  devolvio  una  indicacion  de  fallo
              permanente.

       EAI_AGAIN
              El  servidor  de  nombres  devolvio  una  indicacion  de   fallo
              temporal.  Pruebe mas tarde.

       EAI_SYSTEM
              Otro error de sistema, compruebe errno para mas detalles.

       La  funcion  gai_strerror(3)  transforma  estos  codigos de erro en una
       cadena comprensible, adecuada para el informe de errores.

V'EASE TAMBI'EN

       getipnodebyname(3), getipnodebyaddr(3)