GETNAMEINFO(3)

 .

NOM
getnameinfo - Traduction d'adresse en nom de façon indépendante du protocole

SYNOPSIS
#include <sys/socket.h>
#include <netdb.h>

int getnameinfo(const struct sockaddr *sa, socklen_t salen,
                char *host, size_t hostlen,
                char *serv, size_t servlen, int flags);

DESCRIPTION
La fonction getnameinfo() est la reciproque de getaddrinfo(3) : elle convertit une adresse de socket en un hôte et un service correspondants, de façon indépendante du protocole. Elle combine les fonctionnalités de gethostbyaddr(3) et getservbyport(3) mais contrairement à ces fonctions, getaddrinfo(3) est réentrante et permet aux programmes de supprimer les dépendances IPv4/IPv6. Le paramètre sa est un pointeur vers l'adresse d'une structure de socket générique (de type sockaddr_in ou sockaddr_in6) de taille salen qui contient l'adresse IP d'entrée et le numéro de port. Les paramètres host et serv sont des pointeurs vers des tampons alloués par l'appelant (de tailles respectives hostlen et servlen dans lesquels getnameinfo() place des chaînes de caractères, terminées par l'octet nul, contenant respectivement les noms d'hôte et de service. L'appelant peut préciser qu'aucun nom d'hôte (ou qu'aucun nom de service) n'est nécessaire en fournissant NULL comme paramètre host (ou serv) ou bien en passant un argument hostlen (ou servlen) valant zéro. Quoi qu'il en soit, au moins un nom d'hôte ou un nom de service doit être demandé. Le paramètre flags modifie le comportement de getnameinfo() comme indiqué ci-dessous :

NI_NAMEREQD
    S'il est défini, une erreur se produira si le nom de l'hôte n'a pas pu être déterminé.

NI_DGRAM
    S'il est défini, le service est basé sur des datagrammes (UDP) plutôt que sur un flux (TCP). Cet attribut est nécessaire pour les quelques ports (512-514) qui ont des services différents selon le protocole utilisé : UDP ou TCP.

NI_NOFQDN
    renvoie seulement la partie nom de l'hôte du FQDN (Fully-Qualified Domain Name) pour les hôtes locaux.

NI_NUMERICHOST
    La forme numérique du nom de l'hôte est renvoyée. (Même si ce drapeau n'est pas levé, cela arrivera également lorsque le nom du nœud ne pourra pas être résolu.)

NI_NUMERICSERV
    Si cet attribut est défini, l'adresse du service est renvoyée sous forme numérique. (S'il n'est pas défini, cela sera toujours le cas si le nom du service n'a pas pu être déterminé.)

NI_DGRAM
    Indique que le service est plutôt basé sur des datagrammes (UDP) que sur un flux connecté (TCP). Ce drapeau est nécessaire pour les quelques ports (512-514) qui ont des services différents selon le protocole utilisé : UDP ou TCP.

  Extensions de getaddrinfo() pour les noms de domaines internationalisés

Depuis la glibc 2.3.4, getnameinfo() a été modifiée pour sélectivement permettre que les noms d'hôtes entrant et sortant soient convertis de manière transparente vers ou depuis le format des noms de domaines internationalisés (« Internationalized Domain Name », IDN). (Voir la RFC 3490, Internationalizing Domain Names in Applications (IDNA)). Trois nouveaux attributs ont été ajoutés :

NI_IDN
    Si cet attribut est utilisé, le nom trouvé lors de la résolution des noms est converti, si nécessaire, depuis le format IDN vers l'encodage des paramètres régionaux du système. Les noms au format ASCII ne sont pas affectés par cette conversion, ce qui permet d'utiliser cet attribut dans des programmes et des environnements existants.

NI_IDN_ALLOW_UNASSIGNED, NI_IDN_USE_STD3_ASCII_RULES
    Utiliser ces attributs permet d'activer respectivement les attributs IDNA_ALLOW_UNASSIGNED (permettre des caractères Unicode non assignés) et IDNA_USE_STD3_ASCII_RULES (vérifier la sortie pour être sûr que le nom d'hôte est conforme à STD3) utilisés dans la gestion de l'IDNA.

VALEUR RENVOYÉE
En cas de succès, 0 est renvoyé et les noms du nœud et du service, s'ils sont demandés, sont renseignés sous forme de chaînes terminées par un octet nul, éventuellement tronquées afin de s'adapter aux tailles des tampons spécifiés. En cas d'erreur, un des codes d'erreur non nuls suivants est renvoyé :

ERREURS

EAI_AGAIN
    Le nom ne peut être résolu à cet instant. Réessayer plus tard.

EAI_BADFLAGS
    Le paramètre flags n'est pas valide.

EAI_FAIL
    Une erreur irrécupérable est survenue.

EAI_FAMILY
    La famille d'adresse n'a pas été reconnue, ou bien la taille de l'adresse était invalide pour la famille spécifiée.

EAI_MEMORY
    Pas assez de mémoire.

EAI_NONAME
    Le nom ne peut être résolu avec les paramètres fournis. NI_NAMEREQD est spécifié et le nom de l'hôte ne peut être localisé, ou bien, on n'a demandé ni un nom d'hôte ni un nom de service.

EAI_OVERFLOW
    Le tampon pointé par host ou serv est trop petit.

EAI_SYSTEM
    Une erreur système a eu lieu. Le code d'erreur peut être lu dans errno.

La fonction gai_strerror(3) traduit ces codes d'erreur en une chaîne intelligible, pratique pour soummettre les erreurs.

FICHIERS
/etc/hosts
/etc/nsswitch.conf
/etc/resolv.conf

VERSIONS
getnameinfo() est fournie par la glibc depuis la version 2.1.

CONFORMITÉ
RFC 2553, POSIX.1-2001.

NOTES
Afin d'aider les programmeurs à choisir des tailles raisonnables pour les tampons fournis, <netdb.h> définit les constantes
#define NI_MAXHOST      1025
#define NI_MAXSERV      32

La première est la constante MAXDNAME présente dans les versions récentes du fichier d'entête <arpa/nameser.h> de BIND. La deuxième est déterminée en se basant sur les services répertoriés dans la RFC « Assigned numbers » (Numéros affectés) actuelle.

EXEMPLE
Le code suivant essaie d'obtenir le nom de l'hôte ainsi que le nom du service sous forme numérique, et ce, pour une adresse de socket donnée. Remarquez qu'il n'y a aucune référence à une quelconque famille d'adresse codée en dur.
struct sockaddr *sa;    /* input */
socklent_t len;         /* input */
char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
if (getnameinfo(sa, len, hbuf, sizeof(hbuf), sbuf,
                sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
    printf("host=%s, serv=%s\n", hbuf, sbuf);
La version suivante vérifie si l'adresse de la socket peut se voir associer un nom.
struct sockaddr *sa;    /* input */
socklent_t len;         /* input */
char hbuf[NI_MAXHOST];
if (getnameinfo(sa, len, hbuf, sizeof(hbuf),
                NULL, 0, NI_NAMEREQD))
    printf("could not resolve hostname");
else
    printf("host=%s\n", hbuf);

Un programme exemple utilisant getnameinfo() peut être trouvé dans getaddrinfo(3).

VOIR AUSSI
accept(2), getpeername(2), getsockname(2), recvfrom(2), socket(2), getaddrinfo(3), gethostbyaddr(3), getservbyname(3), getservbyport(3), inet_ntop(3), hosts(5), services(5), hostname(7), named(8)

R. Gilligan, S. Thomson, J. Bound et W. Stevens, Basic Socket Interface Extensions for IPv6, RFC 2553, mars 1999.

Tatsuya Jinmei et Atsushi Onoe, An Extension of Format for IPv6 Scoped Addresses, internet draft, travail en cours. ftp://ftp.ietf.org/internet-drafts/draft-ietf-ipngwg-scopedaddr-format-02.txt

Craig Metz, Protocol Independence Using the Sockets API, compte rendu du sujet freenix : conférence technique annuelle USENIX 2000, juin 2000. http://www.usenix.org/publications/library/proceedings/usenix2000/freenix/metzprotocol.html

TRADUCTION

Ce document est une traduction réalisée par Stéphan Rafin <stephan DOT rafin AT laposte DOT net> le 8 mai 2002 et révisée le 17 juillet 2008.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 3 getnameinfo ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.