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