Loading

NOM

       gethostbyname,   gethostbyaddr,   sethostent,  gethostent,  endhostent,
       h_errno,   herror,    hstrerror,    gethostbyaddr_r,    gethostbyname2,
       gethostbyname2_r,   gethostbyname_r,   gethostent_r   -   Obtenir   des
       informations concernant le réseau

SYNOPSIS

       #include <netdb.h>
       extern int h_errno;

       struct hostent *gethostbyname(const char *name);

       #include <sys/socket.h>       /* pour AF_INET */
       struct hostent *gethostbyaddr(const void *addr,
                                     socklen_t len, int type);

       void sethostent(int stayopen);

       void endhostent(void);

       void herror(const char *s);

       const char *hstrerror(int err);

       /* Extension System V/POSIX */
       struct hostent *gethostent(void);

       /* Extensions GNU */
       struct hostent *gethostbyname2(const char *name, int af);

       int gethostent_r(
               struct hostent *ret, char *buf, size_t buflen,
               struct hostent **result, int *h_errnop);

       int gethostbyaddr_r(const void *addr, socklen_t len, int type,
               struct hostent *ret, char *buf, size_t buflen,
               struct hostent **result, int *h_errnop);

       int gethostbyname_r(const char *name,
               struct hostent *ret, char *buf, size_t buflen,
               struct hostent **result, int *h_errnop);

       int gethostbyname2_r(const char *name, int af,
               struct hostent *ret, char *buf, size_t buflen,
               struct hostent **result, int *h_errnop);

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

       gethostbyname2(), gethostent_r(), gethostbyaddr_r(), gethostbyname_r(),
       gethostbyname2_r() : _BSD_SOURCE || _SVID_SOURCE

       gethostbyname*()   et   gethostbyaddr*()   sont   déconseillées.    Les
       applications  devraient  utiliser getaddrinfo(3) et getnameinfo(3) à la
       place.

       La fonction gethostbyname() renvoie une structure de type hostent  pour
       l’hôte  name.  La  chaîne name est soit un nom d’hôte, soit une adresse
       IPv4 en notation pointée standard (comme pour inet_addr(3)),  soit  une
       adresse  IPv6  avec  la notation points-virgules et points (Cf RFC 1884
       pour la description des adresses IPv6). Si name est une adresse IPv4 ou
       IPv6, aucune recherche supplémentaire n’a lieu et gethostbyname() copie
       simplement la chaîne name dans le champ h_name et le  champ  équivalent
       struct  in_addr  dans  le  champ h_addr_list[0] de la structure hostent
       renvoyée. Si name ne se termine pas par un point,  et  si  la  variable
       d’environnement  HOSTALIASES  est configurée, le fichier d’alias pointé
       par HOSTALIASES sera d’abord parcouru à la  recherche  de  name  (voyez
       hostname(7)  pour  le  format  du  fichier).  Le domaine courant et ses
       parents sont parcourus si name ne se termine pas par un point.

       La fonction gethostbyaddr() renvoie une structure du type hostent  pour
       l’hôte  d’adresse  addr.  Cette  adresse est de longueur len et du type
       type. Les types d’adresse valides sont AF_INET et AF_INET6.  L’argument
       adresse  de l’hôte est un pointeur vers une structure de type dépendant
       du type de l’adresse, par exemple struct in_addr * (probablement obtenu
       via un appel à inet_addr(3)) pour une adresse de type AF_INET.

       La fonction sethostent() indique, si stayopen est vrai (vaut 1), qu’une
       socket TCP connectée doit être utilisée pour interroger le  serveur  de
       noms  et  que  la  connexion  doit  rester  ouverte durant les demandes
       successives. Sinon l’interrogation utilisera des datagrammes UDP.

       La fonction endhostent() ferme la socket TCP  connectée  utilisée  pour
       interroger le serveur de noms.

       La  fonction  (obsolète)  herror()  affiche le message d’erreur associé
       avec la valeur courante de h_errno sur la sortie standard stderr.

       La  fonction  (obsolète)  hstrerror()  reçoit  un  numéro  d’erreur  en
       argument   (typiquement  h_errno)  et  renvoie  la  chaîne  de  message
       d’erreur.

       Les interrogations du serveur de noms effectuées par gethostbyname() et
       gethostbyaddr()  utilisent  les  éléments suivants : le serveur de noms
       named(8), les lignes de /etc/hosts, et l’annuaire  Network  Information
       Service  (NIS  ou  YP), suivant le contenu de la ligne order du fichier
       /etc/host.conf. L’action par défaut  consiste  à  interroger  named(8),
       puis /etc/hosts.

       La structure hostent est définie ainsi dans <netdb.h> :

           struct hostent {
               char  *h_name;            /* Nom officiel de l’hôte */
               char **h_aliases;         /* Liste d’alias */
               int    h_addrtype;        /* Type d’adresse de l’hôte */
               int    h_length;          /* Longueur de l’adresse */
               char **h_addr_list;       /* Liste d’adresses */
           }
           #define h_addr h_addr_list[0] /* for backward compatibility */

       Les membres de la structure hostent sont :

       h_name Nom officiel de l’hôte.

       h_aliases
              Un  tableau, terminé par un pointeur NULL, d’alternatives au nom
              officiel de l’hôte.

       h_addrtype
              Le type d’adresse : actuellement toujours AF_INET ou AF_INET6.

       h_length
              La longueur, en octets, de l’adresse.

       h_addr_list
              Un tableau, terminé par un pointeur NULL, d’adresses réseau pour
              l’hôte, avec l’ordre des octets du réseau.

       h_addr La   première   adresse   dans  h_addr_list  pour  respecter  la
              compatibilité ascendante.

VALEUR RENVOYÉE

       Les fonctions gethostbyname() et gethostbyaddr() renvoient un  pointeur
       vers  la  structure  hostent,  ou  un  pointeur  NULL  si une erreur se
       produit, auquel cas h_errno  contient  le  code  d’erreur.  Lorsqu’elle
       n’est  pas  NULL,  la  valeur  de  retour  peut  pointer sur une donnée
       statique. Voyez les notes plus loin.

ERREURS

       La variable h_errno peut prendre les valeurs suivantes :

       HOST_NOT_FOUND
              L’hôte indiqué est inconnu.

       NO_ADDRESS ou NO_DATA
              Le nom est valide mais ne possède pas d’adresse IP.

       NO_RECOVERY
              Une erreur fatale du serveur de noms est apparue.

       TRY_AGAIN
              Une erreur temporaire du serveur de noms est apparue, essayez un
              peu plus tard.

FICHIERS

       /etc/host.conf
              Fichier de configuration de la résolution de noms.

       /etc/hosts
              Base de données des hôtes.

       /etc/nsswitch.conf
              Configuration du service de noms.

CONFORMITÉ

       POSIX.1-2001  spécifie  gethostbyname(), gethostbyaddr(), sethostent(),
       endhostent(),     gethostent()     et     h_errno.     gethostbyname(),
       gethostbyaddr(),  et  h_errno sont marquées obsolètes dans ce standard.
       POSIX.1-2008   supprime   les   spécifications   de    gethostbyname(),
       gethostbyaddr()  et  h_errno  et recommande à la place l’utilisation de
       getaddrinfo(3) et getnameinfo(3).

NOTES

       Les fonctions gethostbyname() et gethostbyaddr() peuvent  renvoyer  des
       pointeurs  sur  des données statiques susceptibles d’être écrasées d’un
       appel à l’autre. Copier la structure struct hostent ne suffit  pas  car
       elle  contient  elle-même  des  pointeurs.  Une copie en profondeur est
       indispensable.

       Dans l’implémentation BSD originale, l’argument len de  gethostbyname()
       était  un int. Les spécifications SUS-v2 sont défectueuses et déclarent
       le paramètre len de gethostbyaddr() comme étant de  type  size_t  (ceci
       est erroné car il doit obligatoirement être un int, ce que size_t n’est
       pas toujours. POSIX.1-2001 le déclare socklen_t, ce qui  est  correct).
       Consultez également accept(2).

       Le  prototype  BSD  pour  gethostbyaddr()  utilise  const  char * comme
       premier argument.

   Extension System V/POSIX
       POSIX réclame l’appel gethostent(), qui devrait renvoyer  la  prochaine
       entrée  de  la  base  de données des hôtes. Avec DNS/BIND, cela n’a pas
       plus de sens, mais cela peut être raisonnable si la base de données des
       hôtes  est un fichier qui peut être lu ligne par ligne. Sur beaucoup de
       systèmes, une routine de ce nom lit le  fichier  /etc/hosts.  Elle  est
       disponible  que  lorsque la bibliothèque est construite sans la gestion
       DNS. L’équivalent de la glibc ignore les entrées IPv6.  Cette  fonction
       n’est  pas  ré-entrante, mais la glibc propose une version ré-entrante,
       gethostent_r().

   Extensions GNU
       La glibc2 propose aussi une fonction gethostbyname2()  qui  agit  comme
       gethostbyname(), qui permet de préciser la famille à laquelle l’adresse
       doit appartenir.

       La glibc2  propose  aussi  les  versions  ré-entrantes  gethostent_r(),
       gethostbyaddr_r(),  gethostbyname_r() et gethostbyname2_r(). L’appelant
       fournit une structure hostent via ret qui sera remplie en cas de succès
       et un tampon de travail temporaire buf de taille buflen. Après l’appel,
       result pointera vers le résultat en cas de succès. En cas  d’erreur  ou
       si  aucune  entrée  n’a  été  trouvée, result vaudra NULL Les fonctions
       renvoient 0 en cas de succès et une valeur non nulle en  cas  d’erreur.
       En  plus  des  erreurs renvoyées par ces fonctions ré-entrantes, si buf
       est trop petit, les fonctions renvoient ERANGE et  l’appel  devra  être
       effectué  par  la  suite avec un tampon plus grand. La variable h_errno
       n’est pas modifiée, mais l’adresse d’une variable où est stocké le code
       d’erreur est transmise dans h_errnop.

BOGUES

       gethostbyname()  ne  reconnaît  pas  les éléments d’une adresse IPv4 en
       notation pointée si ces éléments sont exprimés en hexadécimal.

VOIR AUSSI

       getaddrinfo(3), getnameinfo(3),  inet(3),  inet_ntop(3),  inet_pton(3),
       resolver(3), hosts(5), nsswitch.conf(5), hostname(7), named(8)

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  et  mise  à  jour  par  Christophe
       Blaess  <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis 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> ».

                                 15 mars 2009                 GETHOSTBYNAME(3)