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