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);
Exigences de macros de test de fonctionnalités pour la glibc (voir
feature_test_macros(7)) :
getnameinfo() : _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE
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, 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 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 noeud 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 getaddrinfo() 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 noeud 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 spécifié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 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
Plus de mémoire disponible.
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, 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 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
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).
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
COLOPHON
Cette page fait partie de la publication 3.23 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
Cette page de manuel a été traduite par Stéphan Rafin <stephan DOT
rafin AT laposte DOT net> en 2002, puis a été mise à jour par Alain
Portal <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
disposition sur http://manpagesfr.free.fr/.
Les mises à jour et corrections de la version présente dans Debian sont
directement gérées par Florentin Duneau <fduneau@gmail.com> et l’équipe
francophone de traduction de Debian.
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> 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> ».