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.