GETNAMEINFO
Section : Manuel du programmeur Linux (
3)
Mise à jour de la version anglaise : 18 juin 2008
Index
Menu principal
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.
Index
- NOM
-
- SYNOPSIS
-
- DESCRIPTION
-
- Extensions de getaddrinfo() pour les noms de domaines internationalisés
-
- VALEUR RENVOYÉE
-
- ERREURS
-
- FICHIERS
-
- VERSIONS
-
- CONFORMITÉ
-
- NOTES
-
- EXEMPLE
-
- VOIR AUSSI
-
- TRADUCTION
-
Dernière mise à jour : 17 juillet 2008