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)