man getnameinfo (3): 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);

Exigences de macros de test de fonctionnalités pour la glibc (consultez feature_test_macros(7)) :

getnameinfo() : _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE

DESCRIPTION

La fonction getnameinfo() est la réciproque 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, getnameinfo() 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 un 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 paramètre 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: 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.
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 déterminé.)
NI_NUMERICSERV: Si cet attribut est défini, la forme numérique du service est renvoyée. (S'il n'est pas défini, cela arrivera également si le nom du service n'a pas pu être déterminé.)

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

Depuis la glibc 2.3.4, getnameinfo() a été modifié pour sélectivement permettre que les noms de domaines soient convertis vers ou depuis le format des noms de domaines internationalisés (IDN). Consultez la RFC 3490, Internationalizing Domain Names in Applications (IDNA).Trois nouveaux attributs ont été ajoutés :

NI_IDN: Si cet attribut est utilisé, alors le nom trouvé lors de la résolution des noms est converti depuis le format IDN vers la locale du système si nécessaire. 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 caractère nul, éventuellement tronquées afin de s'adapter aux tailles des tampons indiqués. En cas d'erreur, un des codes d'erreur suivants est renvoyé :

EAI_AGAIN: Le nom ne peut être résolu à cet instant. Réessayer plus tard.
EAI_BADFLAGS: Le paramètre flags n'est pas valable.
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 incorrecte pour la famille indiquée.
EAI_MEMORY: Plus de mémoire disponible.
EAI_NONAME: Le nom ne peut être résolu avec les paramètres fournis. NI_NAMEREQD est indiqué et le nom de l'hôte ne peut être localisé, ou ni un nom d'hôte ni un nom de service n’a été demandé.
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 de caractères compréhensible, utilisable pour rendre compte du problème.

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

Depuis la glibc 2.8, ces définitions sont exposées seulement si l'une des macros de test de fonctionnalités _BSD_SOURCE, _SVID_SOURCE, ou _GNU_SOURCE est définie.

La première est la constante MAXDNAME présente dans les versions récentes du fichier d'en-têtes <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 ».

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 */
socklen_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 */
socklen_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 d'exemple utilisant getnameinfo() peut être trouvé dans getaddrinfo(3).

COLOPHON

Cette page fait partie de la publication 3.65 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies peuvent être trouvées à l'adresse http://www.kernel.org/doc/man-pages/.

TRADUCTION

Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a <http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet perkamon <http://perkamon.alioth.debian.org/>.

Stéphan Rafin (2002), Alain Portal <http://manpagesfr.free.fr/> (2006). Florentin Duneau et l'équipe francophone de traduction de Debian (2006-2009).

Veuillez signaler toute erreur de traduction en écrivant à <[email protected]> ou par un rapport de bogue sur le paquet manpages-fr.

Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande « man -L C <section> <page_de_man> ».