Sous-routine getaddrinfo

Objectif

Conversion de nom d'hôte en adresse indépendante du protocole.

Bibliothèque

Bibliothèque (libc.a)

Syntaxe

#include <sys/socket.h>
#include <netdb.h>
int getaddrinfo (hostname, servname, hints, res)
const char *hostname;
const char *servname;
const struct addrinfo *hints;
struct addrinfo **res;

Descriptif

Les paramètres hostname et servname décrivent le nom d'hôte et/ou le nom de service à référencer. Zéro ou l'un de ces arguments peut être NULL. Un nom d'hôte non NULL peut être un nom d'hôte ou une chaîne d'adresse d'hôte numérique (en notation décimale à point pour IPv4 ou en hexadécimal pour IPv6). Un nom de serveur non NULL peut être un nom de service ou un numéro de port décimal.

Le paramètre hints indique des indications concernant les informations de retour souhaitées. Les paramètres hostname et servname sont des pointeurs vers des chaînes à terminaison nulle ou NULL. L'un de ces arguments ou les deux doivent être un pointeur non-NULL. Dans un scénario client normal, les paramètres hostname et servname sont spécifiés. Dans le scénario de serveur normal, seul le paramètre servname est spécifié. Une chaîne de nom d'hôte non NULL peut être un nom d'hôte ou une chaîne d'adresse d'hôte numérique (par exemple, une adresse IPv4 à notation décimale à point ou une adresse hexadécimale IPv6 ). Une chaîne servname non NULL peut être un nom de service ou un numéro de port décimal.

L'appelant peut éventuellement transmettre une structure addrinfo , pointée par le paramètre hints , pour fournir des indications concernant le type de socket pris en charge par l'appelant. Dans cette structure hints , tous les membres autres que ai_flags, ai_eflags ai_family, ai_socktype, et ai_protocol doit être zéro ou un pointeur NULL. La valeur PF_UNSPEC pour ai_family signifie que l'appelant accepte n'importe quelle famille de protocoles. La valeur zéro pour ai_socktype signifie que l'appelant accepte tout type de socket. La valeur zéro pour ai_protocol signifie que l'appelant accepte n'importe quel protocole. Par exemple, si l'appelant gère uniquement TCP et non UDP, le membre ai_socktype de la structure hints doit être défini sur SOCK_STREAM lorsque la sous-routine getaddrinfo est appelée. Si l'appelant gère uniquement IPv4 et non IPv6, le membre ai_family de la structure hints doit être défini sur PF_INET lorsque getaddrinfo est appelé. Si le paramètre hints dans getaddrinfo est un pointeur NULL, il est le même que si l'appelant remplit une structure addrinfo initialisée à zéro avec ai_family défini sur PF_UNSPEC.

En cas de retour réussi, un pointeur vers une liste liée d'une ou de plusieurs structures addrinfo est renvoyé via le paramètre res . L'appelant peut traiter chaque structure addrinfo de cette liste en suivant le pointeur ai_next jusqu'à ce qu'un pointeur NULL soit détecté. Dans chaque structure addrinfo renvoyée, les trois membres ai_family, ai_socktype, et ai_protocol sont les arguments correspondants pour un appel à la sous-routine socket . Dans chaque structure addrinfo , le membre ai_addr pointe vers une structure d'adresse de socket renseignée dont la longueur est spécifiée par le membre ai_addrlen .

Si le bit AI_PASSIVE est défini dans le membre ai_flags de la structure hints , l'appelant prévoit d'utiliser la structure d'adresse de socket renvoyée dans un appel à la sous-routine bind . Si le paramètre hostname est un pointeur NULL, la partie adresse IP de la structure d'adresse de socket sera définie sur INADDR_ANY pour une adresse IPv4 ou sur IN6ADDR_ANY_INIT pour une adresse IPv6 .

Si le bit AI_PASSIVE n'est pas défini dans le membre ai_flags de la structure de suggestions, la structure d'adresse de socket renvoyée est prête pour un appel à la sous-routine connect (pour un protocole orienté connexion) ou à la connexion, sendtoou sous-routine sendmsg (pour un protocole sans connexion). Si le paramètre hostname est un pointeur NULL, la partie adresse IP de la structure d'adresse de socket est définie sur l'adresse de bouclage.

Si le bit AI_CANONNAME est défini dans le membre ai_flags de la structure des suggestions, en cas de succès, le membre ai_canonname de la première structure addrinfo de la liste liée pointe vers une chaîne à terminaison NULL contenant le nom canonique du nom d'hôte spécifié.

Si l'indicateur AI_NUMERICHOST est spécifié, une chaîne de nom de noeud non NULL fournie est une chaîne d'adresse hôte numérique. Sinon, une erreur (EAI_NONAME) est renvoyée. Cet indicateur empêche tout type de service de résolution de nom (tel que DNS) d'être appelé.

Si l'indicateur AI_NUMERICSERV est spécifié, une chaîne de nom de serveur non NULL fournie est une chaîne de port numérique. Sinon, une erreur (EAI_NONAME) est renvoyée. Cet indicateur empêche tout type de service de résolution de nom d'être appelé.

Si l'indicateur AI_V4MAPPED est spécifié avec une valeur ai_family de AF_INET6, La sous-routine getaddrinfo renvoie des adresses IPv4-mapped IPv6 lorsqu'aucune adresse IPv6 correspondante (ai_addrlen est 16) n'est trouvée. Par exemple, lors de l'utilisation de DNS, si aucun enregistrement AAAA ou A6 n'est trouvé, une requête est effectuée pour les enregistrements A. Tous les éléments trouvés sont renvoyés en tant qu'adresses IPv6 IPv4-mapped . L'indicateur AI_V4MAPPED est ignoré sauf si ai_family est égal à AF_INET6.

Si AI_EXTFLAGS est spécifié dans le membre ai_flags de la structure des suggestions et que ai_eflags est spécifié comme une valeur différente de zéro, l'algorithme de sélection d'adresse est affecté. L'algorithme de sélection d'adresses commande la liste des structures addrinfo retournées à l'aide d'un ensemble de règles ordonnées (RFC 3484) prenant en compte l'adresse contenue dans le membre ai_addr de chaque structure addrinfo et les adresses sources à partir desquelles cette adresse peut être atteinte. L'ai_eflags exprime les préférences, ce qui signifie que les règles décrites ci-dessous seront appliquées si une règle plus élevée n'a pas ordonné l'ensemble d'adresses auparavant.

ai_eflags peut être défini sur une combinaison des options suivantes:

Par exemple, IPV6_PREFER_SRC_TMP ai_eflags signifie que l'algorithme de sélection d'adresse ordonne les structures addrinfo renvoyées avec des adresses accessibles à partir d'une adresse temporaire avant celles avec des adresses accessibles à partir d'une adresse publique chaque fois que cela est possible. La définition d'indicateurs contradictoires (par exemple, IPV6_PREFER_SRC_TMP et IPV6_PREFER_SRC_PUBLIC) entraîne l'erreur EINVAL.

Si l'indicateur AI_ADDRCONFIG est spécifié, une requête pour les enregistrements AAAA ou A6 ne doit se produire que si au moins une adresse source IPv6 est configurée pour le noeud. Une requête pour les enregistrements A ne doit se produire que si au moins une adresse source IPv4 est configurée pour le noeud. L'adresse de bouclage n'est pas considérée comme valide en tant qu'adresse source configurée.

Toutes les informations renvoyées par la sous-routine getaddrinfo sont allouées de manière dynamique: les structures addrinfo , les structures d'adresse de socket et les chaînes de nom d'hôte canoniques pointées par les structures addrinfo . Pour renvoyer ces informations au système, la sous-routine freeaddrinfo est appelée.

La structure addrinfo est définie comme suit:

struct addrinfo {
  int               ai_flags;          /* AI_PASSIVE, AI_CANONNAME */
  int               ai_family;         /* PF_xxx */
  int               ai_socktype;       /* SOCK_xxx */
  int               ai_protocol;       /* 0 or IP=PROTO_xxx for IPv4 and IPv6 */
  size_t            ai_addrlen;        /* length of ai_addr */
  char              *ai_canonname;     /* canoncial name for hostname */
  struct sockaddr   *ai_addr;          /* binary address */
  struct addrinfo   *ai_next;          /* next structure in linked list */
  int ai_eflags; /* Extended flags for special usage */
}

Valeurs renvoyées

Si la requête aboutit, un pointeur vers une liste liée d'une ou de plusieurs structures addrinfo est renvoyé via le paramètre res . Une valeur de retour zéro indique que l'opération a abouti. Si la requête échoue, un code d'erreur différent de zéro est renvoyé.

Codes d'erreur

Les noms suivants sont des codes d'erreur différents de zéro. Pour plus d'informations, voir netdb.h .