Provided by:
manpages-fr_1.67.0-1_all 
NOM
getaddrinfo, freeaddrinfo, gai_strerror - Traduction d’adresses et de
services réseau.
SYNOPSIS
#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);
char * gai_strerror(int errcode);
DESCRIPTION
La fonction getaddrinfo(3) combine les possibilités offertes par les
fonctions getipnodebyname(3), getipnodebyaddr(3), getservbyname(3), et
getservbyport(3) en une unique interface. La fonction getaddrinfo(3),
adaptée aux contextes multithreads, crée une ou plusieurs structures
d’adresses de socket, utilisables par bind(2) et connect(2) pour créer
une socket de client ou de serveur.
La fonction getaddrinfo(3) n’est pas limitée aux structures d’adresses
IPv4, elle permet également la création de structures IPv6 si le
support en est disponible. Ces structures peuvent être utilisées
directement par bind(2) ou connect(2), pour préparer une socket de
client ou de serveur.
La structure addrinfo utilisée par cette fonction contient les membres
suivants :
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;
};
La fonction getaddrinfo(3) fait pointer res vers une liste de
structures addrinfo nouvellement allouées, chaînées par leurs membres
ai_next. La liste peut contenir plusieurs structures addrinfo pour
plusieurs raisons, par exemple : l’hôte fonctionne en multi-home, ou le
même service est disponible sur plusieurs types de sockets (une socket
SOCK_STREAM et une socket SOCK_DGRAM par exemple).
Les membres ai_family, ai_socktype, et ai_protocol ont la même
signification que leurs homologues de l’appel-système socket(2). La
fonction getaddrinfo(3) renvoie les adresses de sockets autant en IPv4
qu’en IPv6 (ai_family contiendra PF_INET ou PF_INET6).
L’argument hints permer de préciser le type préféré de socket ou de
protocole. Un argument hints NULL indique que tout type d’adresse ou
de protocole est acceptable. Si ce paramètre n’est pas NULL il doit
pointer sur une structure addrinfo dont les membres ai_family,
ai_socktype, et ai_protocol indiquent les types de socket préférés.
PF_UNSPEC dans le membre ai_family indique que toute famille de
d’adresse (autant IPv4 que IPv6, par exemple) est acceptable. De même,
un 0 dans les membres ai_socktype ou ai_protocol indique que tout type
de socket ou de protocole est admis. Le membre ai_flags indique des
options supplémentaires décrites plus bas. Divers attributs sont
regroupés par un OU binaire. Tous les autres membres de l’argument
hints doivent contenir 0 ou être des pointeurs NULL.
L’argument node ou l’argument service peuvent être NULL, mais pas les
deux en même temps. node indique soit une adresse réseau en format
numérique (décimal pointé pour l’IPv4, hexadécimal pour l’IPv6), soit
un nom d’hôte, dont l’adresse réseau est alors résolue. Si le membre
ai_flags de l’argument hints contient l’attribut AI_NUMERICHOST alors
le paramètre node devra être une adresse réseau numérique. L’attribut
AI_NUMERICHOST empêche toute tentative - éventuellement longue - de
résolution de nom d’hôte.
La fonction getaddrinfo(3) crée une liste chaînée de structures
addrinfo, une pour chaque adresse réseau soumise aux restrictions
imposées par l’argument hints. Le membre ai_canonname pointera vers le
nom officiel de l’hôte si le membre ai_flags de l’argument hints
contient l’attribut AI_CANONNAME. Les membres ai_family, ai_socktype,
et ai_protocol indiquent les paramètres de création de socket. Un
pointeur vers l’adresse de la socket est placé dans le membre ai_addr,
et la longueur de l’adresse de la socket, en octets, est inscrite dans
le membre ai_addrlen de la structure.
Si l’argument node est NULL, l’adresse réseau dans chaque structure
d’adresse est initialisée en fonction de l’attribut AI_PASSIVE que l’on
inscrit dans le membre ai_flags de l’argument hints. L’adresse réseau
de chaque structure sera laissée vide si l’attribut AI_PASSIVE est
présent. Ceci est utilisé par les serveurs qui désirent accepter les
connexions des clients sur n’importe quelle interface réseau.
L’adresse réseau sera remplie avec l’adresse de boucle loopback si
l’attribut AI_PASSIVE n’est pas utilisé. Ceci est utilisé par les
clients qui désirent se connecter sur un serveur fonctionnant sur le
même hôte.
L’argument service indique le numéro de port au sein de l’adresse
réseau de la socket. Si service est NULL le numéro de port restera non
initialisé.
La fonction freeaddrinfo(3) libère la mémoire qui a été allouée
dynamiquement pour la liste chaînée res.
VALEUR RENVOYÉE
getaddrinfo(3) renvoie 0 si elle réussit, ou l’un des codes d’erreur
non-nuls suivants :
EAI_FAMILY
La famille d’adresse réclamée n’est pas supportée du tout.
EAI_SOCKTYPE
Le type de socket demandé n’est pas supporté.
EAI_BADFLAGS
ai_flags contient des attributs invalides.
EAI_NONAME
Le contenu du champ node ou de service est inconnu. Cette
erreur est aussi renvoyée si node et service sont simultanément
NULL.
EAI_SERVICE
Le service demandé n’est pas disponible pour le type de socket
réclamé. Il peut être disponible pour un autre type de socket.
EAI_ADDRFAMILY
L’hôte indiqué n’a pas d’adresse dans la famille réseau
demandée.
EAI_NODATA
L’hôte existe mais n’a pas d’adresse réseau définie.
EAI_MEMORY
Pas assez de mémoire.
EAI_FAIL
Le serveur de noms a renvoyé une erreur définitive.
EAI_AGAIN
Le serveur de noms a renvoyé une erreur temporaire. Réessayez
plus tard.
EAI_SYSTEM
Autre erreur système, voir errno pour plus de détail.
La fonction gai_strerror(3) traduit ces codes d’erreur en une chaîne de
caractères compréhensible, utilisable pour rendre compte du problème.
CONFORMITÉ
POSIX 1003.1-2003. La fonction getaddrinfo() est documentée dans la
RFC 2553.
VOIR AUSSI
getipnodebyname(3), getipnodebyaddr(3)
TRADUCTION
Christophe Blaess, 2000-2003.