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)