gethostbyname

GETHOSTBYNAME(3)           Linux-Programmierhandbuch          GETHOSTBYNAME(3)



BEZEICHNUNG
       gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent,
       h_errno, herror, hstrerror, gethostbyaddr_r, gethostbyname2,
       gethostbyname2_r, gethostbyname_r, gethostent_r - ermittelt den
       Netzwerkeintrag für einen Host

ÃBERSICHT
       #include <netdb.h>
       extern int h_errno;

       struct hostent *gethostbyname(const char *name);

       #include <sys/socket.h>       /* für 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);

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

       /* GNU-Erweiterungen */
       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);

   Mit Glibc erforderliche Makros (siehe feature_test_macros(7)):

       gethostbyname2(), gethostent_r(), gethostbyaddr_r(), gethostbyname_r(),
       gethostbyname2_r():
           Seit Glibc 2.19:
               _DEFAULT_SOURCE
           Glibc-Versionen bis einschlieÃlich 2.19:
               _BSD_SOURCE || _SVID_SOURCE

       herror(), hstrerror():
           Seit Glibc 2.19:
               _DEFAULT_SOURCE
           Glibc 2.8 bis 2.19:
               _BSD_SOURCE || _SVID_SOURCE
           Vor Glibc 2.8:
               none

       h_errno:
           Seit Glibc 2.19:
               _DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L
           Glibc 2.12 bis 2.19:
               _BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L
           Vor Glibc 2.12:
               none

BESCHREIBUNG
       Die Funktionen gethostbyname*(), gethostbyaddr*(), herror() und
       hstrerror() sind veraltet. Anwendungen sollten stattdessen
       getaddrinfo(3), getnameinfo(3) und gai_strerror(3) verwenden.

       Die Funktion gethostbyname() gibt eine Struktur vom Typ hostent für
       den angegebenen Host name zurück. Darin ist name entweder ein
       Host-Name oder eine IPv4-Adresse in der Standard-Punktnotation. Falls
       name eine IPv4-Adresse ist, wird nicht gesucht und gethostbyname()
       kopiert einfach nur den namen und dessen struct in_addr-Ãquivalent in
       das Feld h_addr_list[0] der zurückgegebenen hostent-Struktur. Falls
       name nicht mit einem Punkt endet und die Umgebungsvariable HOSTALIASES
       gesetzt ist, wird zuerst die von HOSTALIASES bestimmte Aliasdatei nach
       dem namen durchsucht (siehe hostname(7) für das Dateiformat). Falls
       der name nicht mit einem Punkt endet, werden die aktuelle Domain und
       ihre übergeordneten Domains durchsucht.

       Die Funktion gethostbyaddr() gibt für die angegebene Adresse addr eine
       Struktur vom Typ hostent mit der Länge len und dem Adresstyp type
       zurück. Mögliche Adresstypen sind AF_INET und AF_INET6. Das Argument
       addr ist ein Zeiger auf eine Struktur, die vom Adresstyp abhängt,
       beispielsweise eine struct in_addr * (möglicherweise ermittelt durch
       einen Aufruf von inet_addr(3)) für den Adresstyp AF_INET.

       Falls stayopen wahr (true(1)) ist, legt die Funktion sethostent() fest,
       dass eine bestehende TCP-Verbindung für Nameserveranfragen genutzt
       werden soll und dass die Verbindung für die nachfolgenden Anfragen
       bestehen bleiben soll. Ansonsten werden für Nameserveranfragen
       UDP-Datagramme benutzt.

       Die Funktion endhostent() beendet die Nutzung einer TCP-Verbindung für
       Namerserveranfragen.

       Die (veraltete) Funktion herror() gibt die zum aktuellen Wert von
       h_errno gehörende Fehlermeldung auf stderr aus.

       Die (veraltete) Funktion hstrerror() ermittelt zu einer Fehlernummer
       (normalerweise h_errno) die zugehörige Zeichenkette mit der
       Fehlermeldung.

       Die durch gethostbyname() und gethostbyaddr() durchgeführten
       Domain-Name-Abfragen verlassen sich auf die konfigurierten Quellen des
       »Name Service Switch« (nsswitch.conf(5)) oder einen lokalen
       Name-Server (named(8)). StandardmäÃig werden die Quellen des »Name
       Service Switch« (nsswitch.conf(5)) abgefragt und, falls das
       fehlschlägt, der lokale Name-Server (named(8)).

   Geschichtliches
       Die Datei nsswitch.conf(5) ist die moderne Art, um die Reihenfolge der
       Rechnerermittlungen zu steuern.

       In Glibc 2.4 und älter wurde das Schlüsselwort order verwandt, um die
       Reihenfolge der Rechnerermittlungen, wie sie in /etc/host.conf
       (host.conf(5)) definiert sind, zu steuern.

       Die Struktur hostent ist in <netdb.h> wie folgt definiert:

           struct hostent {
               char  *h_name;            /* offizieller Name des Rechners */
               char **h_aliases;         /* Aliasliste */
               int    h_addrtype;        /* Host-Adresstyp */
               int    h_length;          /* Länge der Adresse */
               char **h_addr_list;       /* Adressliste */
           }
           #define h_addr h_addr_list[0] /* für Abwärtskompatibilität */

       Die Elemente der hostent-Struktur sind:

       h_name der offizielle Name des Rechners

       h_aliases
              Ein Feld mit den alternativen Namen des Rechners, gefolgt von
              einem NULL-Zeiger.

       h_addrtype
              der Adresstyp, z.Zt. immer AF_INET oder AF_INET6

       h_length
              die Länge der Adresse in Bytes

       h_addr_list
              ein Feld von Zeigern auf Netzwerkadressen für den Rechner (in
              der Netzwerk-Bytereihenfolge), gefolgt von einem Null-Zeiger

       h_addr die erste Adresse in h_addr_list, für Abwärtskompatibilität

RÃCKGABEWERT
       Die Funktionen gethostbyname() und gethostbyaddr() geben eine
       hostent-Struktur zurück. Bei einem Fehler wird ein Null-Zeiger
       zurückgegeben. In diesem Fall enthält die Variable h_errno die
       Fehlernummer. Falls der Zeiger von NULL verschieden ist, kann der
       Rückgabewert auf statische Daten weisen; siehe die folgenden
       Anmerkungen.

FEHLER
       Die Variable h_errno kann folgende Werte annehmen:

       HOST_NOT_FOUND
              Der angegebene Rechner ist unbekannt.

       NO_DATA
              Der angeforderte Name ist gültig aber verfügt über keine
              IP-Adresse. Ein anderer Anfragetyp beim Nameserver für diese
              Domain könnte eine Antwort liefern. Die Konstante NO_ADDRESS
              ist ein Synonym für NO_DATA.

       NO_RECOVERY
              Ein nichtbehebbarer Nameserverfehler ist aufgetreten.

       TRY_AGAIN
              Beim maÃgebenden Nameserver ist ein vorübergehender Fehler
              aufgetreten. Versuchen Sie es später noch einmal.

DATEIEN
       /etc/host.conf
              Konfigurationsdatei des Resolvers (Namensauflöser)

       /etc/hosts
              Host-Datenbankdatei

       /etc/nsswitch.conf
              Konfigurationsdatei für »name service switch«

ATTRIBUTE
       Siehe attributes(7) für eine Erläuterung der in diesem Abschnitt
       verwandten Ausdrücke.

       ┌───────────────────┬────────────────────────┬───────────────────────────────┐
       │Schnittstelle      Attribut               Wert                          │
       ├───────────────────┼────────────────────────┼───────────────────────────────┤
       │gethostbyname()    │ Multithread-Fähigkeit │ MT-Unsafe race:hostbyname env │
       │                   │                        │ locale                        │
       ├───────────────────┼────────────────────────┼───────────────────────────────┤
       │gethostbyaddr()    │ Multithread-Fähigkeit │ MT-Unsafe race:hostbyaddr env │
       │                   │                        │ locale                        │
       ├───────────────────┼────────────────────────┼───────────────────────────────┤
       │sethostent(),      │ Multithread-Fähigkeit │ MT-Unsafe race:hostent env    │
       │endhostent(),      │                        │ locale                        │
       │gethostent_r()     │                        │                               │
       ├───────────────────┼────────────────────────┼───────────────────────────────┤
       │herror(),          │ Multithread-Fähigkeit │ MT-Safe                       │
       │hstrerror()        │                        │                               │
       ├───────────────────┼────────────────────────┼───────────────────────────────┤
       │gethostent()       │ Multithread-Fähigkeit │ MT-Unsafe race:hostent        │
       │                   │                        │ race:hostentbuf env locale    │
       ├───────────────────┼────────────────────────┼───────────────────────────────┤
       │gethostbyname2()   │ Multithread-Fähigkeit │ MT-Unsafe race:hostbyname2    │
       │                   │                        │ env locale                    │
       ├───────────────────┼────────────────────────┼───────────────────────────────┤
       │gethostbyaddr_r(), │ Multithread-Fähigkeit │ MT-Safe env locale            │
       │gethostbyname_r(), │                        │                               │
       │gethostbyname2_r() │                        │                               │
       └───────────────────┴────────────────────────┴───────────────────────────────┘
       In der obigen Tabelle bedeutet hostent in race:hostent, dass, falls
       eine der Funktionen sethostent(), gethostent(), gethostent_r() oder
       endhostent() in verschiedenen Threads eines Programms parallel verwandt
       werden, konkurrierende Zugriffe auf Daten (»data races«) auftreten
       könnten.

KONFORM ZU
       POSIX.1-2001 beschreibt gethostbyname(), gethostbyaddr(), sethostent(),
       endhostent(), gethostent() und h_errno; gethostbyname(),
       gethostbyaddr() und h_errno sind in diesem Standard als allmählich
       auÃer Dienst stellend gekennzeichnet. POSIX.1-2008 entfernt die
       Beschreibungen von gethostbyname(), gethostbyaddr() nd h_errno und
       empfiehlt stattdessen die Verwendung von getaddrinfo(3) und
       getnameinfo(3).

ANMERKUNGEN
       Die Funktionen gethostbyname() und gethostbyaddr() können Zeiger auf
       statische Daten zurückgeben, welche bei späteren Aufrufen
       überschrieben werden könnten. Das Kopieren von struct hostent ist
       nicht ausreichend, weil sie Zeiger enthält. Eine tiefe Kopie ist
       erforderlich.

       In der ursprünglichen BSD-Implementierung von gethostbyname() war das
       Argument  len ein int. Der Standard SUSv2 ist fehlerhaft und weist dem
       Argument len von gethostbyaddr() den Typ size_t zu. (Das ist falsch,
       weil es int sein muss und das für size_t nicht der Fall ist.
       POSIX.1-2001 macht es zusocklen_t, was in Ordnung ist.) Siehe auch
       accept(2).

       Der BSD-Prototyp für gethostbyaddr() verwendet const char * als
       Datentyp für das erste Argument.

   System V/POSIX-Erweiterung
       POSIX verlangt die Existenz der Funktion gethostent(), die den
       nächsten Eintrag in der Host-Datenbank zurückgeben sollte. Bei der
       Verwendung von DNS/BIND ergibt das nicht viel Sinn, aber es kann
       sinnvoll sein, wenn die Host-Datenbank eine Datei ist, die Zeile für
       Zeile gelesen werden kann. Auf vielen Systemen liest eine Routine mit
       diesem Namen aus der Datei /etc/hosts. Es kann sein, dass sie nur
       verfügbar ist, wenn die Bibliothek ohne DNS-Unterstützung gebaut
       wurde. Die Glibc-Version ignoriert Ipv6-Einträge. Diese Funktion ist
       nicht ablaufinvariant. Glibc stellt die ablaufinvariante Version
       gethostent_r() bereit.

   GNU-Erweiterungen
       Glibc2 enthält auch gethostbyname2(), welche wie gethostbyname()
       arbeitet, ermöglicht aber die Vorgabe der Adressfamilie, zu der die
       Adresse gehören muss.but permits to specify the address family to
       which the address must belong.

       Glibc2 hat auch ablaufinvariante Versionen von gethostent_r(),
       gethostbyaddr_r(), gethostbyname_r() und gethostbyname2_r(). Der
       Aufrufende stellte eine hostent-Struktur ret, die bei Erfolg
       ausgefüllt wird, und einen temporären Arbeitspuffer buf der GröÃe
       buflen bereits. Nach dem Aufruf zeigt bei Erfolg result auf das
       Ergebnis. Im Falle eines Fehlers oder wenn kein Eintrag gefunden wird,
       ist result NULL. Die Funktionen liefern 0 bei Erfolg und bei einem
       Fehler eine von Null verschiedene Fehlernummer. Zusätzlich zu den
       Fehlern, die von den nicht ablaufinvarianten Versionen dieser
       Funktionen zurückgegeben werden:Diese Funktionen melden ERANGE, falls
       buf zu klein war. In diesem Fall sollte der Aufruf mit einem gröÃeren
       Puffer wiederholt werden. Die globale Variable h_errno wird nicht
       verändert, sondern die Adresse einer Variablen zur Speicherung von
       Fehlernummern wird in h_errnop übergeben.

FEHLER
       gethostbyname() erkennt in IPv4-Adresszeichenketten in Punktnotation
       keine Bestandteile in hexadezimaler Notation.

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

KOLOPHON
       Diese Seite ist Teil der Veröffentlichung 5.03 des Projekts
       Linux-man-pages. Eine Beschreibung des Projekts, Informationen, wie
       Fehler gemeldet werden können sowie die aktuelle Version dieser Seite
       finden sich unter https://www.kernel.org/doc/man-pages/.


ÃBERSETZUNG
       Die deutsche Ãbersetzung dieser Handbuchseite wurde von Martin Eberhard
       Schauer <Martin.E.Schauer@gmx.de> und Helge Kreutzmann
       <debian@helgefjell.de> erstellt.

       Diese Ãbersetzung ist Freie Dokumentation; lesen Sie die GNU General
       Public License Version 3 oder neuer bezüglich der Copyright-
       Bedingungen. Es wird KEINE HAFTUNG übernommen.

       Wenn Sie Fehler in der Ãbersetzung dieser Handbuchseite finden,
       schicken Sie bitte eine E-Mail an <debian-l10n-
       german@lists.debian.org>.



                              15. September 2017              GETHOSTBYNAME(3)