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 Rechner

BIBLIOTHEK
Standard-C-Bibliothek (libc, -lc)

ÜBERSICHT
#include <netdb.h>

void sethostent(int offenhalten);
void endhostent(void);

[[veraltet]] extern int h_errno;

[[veraltet]] struct hostent *gethostbyname(const char *name);
[[veraltet]] struct hostent *gethostbyaddr(socklen_t Größe;
                                           const void Adr[Größe],
                                           socklen_t Größe, int Typ);

[[veraltet]] void herror(const char *s);
[[veraltet]] const char *hstrerror(int fehler);

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

/* GNU-Erweiterungen */
[[veraltet]]
struct hostent *gethostbyname2(const char *name, int af);

int gethostent_r(size_t Puffgröße;
                 struct hostent *restrict ret,
                 char Puffer[restrict Puffgröße], size_t Puffgröße,
                 struct hostent **restrict ergebnis,
                 int *restrict h_errnop);

[[veraltet]]
int gethostbyaddr_r(socklen_t Größe, size_t Puffgröße;
                 const void addr[restrict Größe], socklen_t Größe,
                 int Typ,
                 struct hostent *restrict ret,
                 char Puffer[restrict Puffgröße], size_t Puffgröße,
                 struct hostent **restrict ergebnis,
                 int *restrict h_errnop);
[[veraltet]]
int gethostbyname_r(size_t Puffgröße;
                 const char *restrict name,
                 struct hostent *restrict ret,
                 char Puffer[restrict Puffgröße], size_t Puffgröße,
                 struct hostent **restrict ergebnis,
                 int *restrict h_errnop);
[[veraltet]]
int gethostbyname2_r(size_t Puffgröße;
                 const char *restrict name, int af,
                 struct hostent *restrict ret,
                 char Puffer[restrict Puffgröße], size_t Puffgröße,
                 struct hostent **restrict ergebnis,
                 int *restrict h_errnop);

    Mit Glibc erforderliche Feature-Test-Makros (siehe feature_test_macros(7)):

gethostbyname2(), gethostent_r(), gethostbyaddr_r(), gethostbyname_r(), gethostbyname2_r():
    Seit Glibc 2.19:
        _DEFAULT_SOURCE
    Glibc bis zu 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.

Wenn offenhalten wahr (d.h. 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 Funktion gethostbyname() gibt eine Struktur vom Typ hostent für den angegebenen Rechner name zurück. Darin ist name entweder ein Rechner-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 Adr eine Struktur vom Typ hostent mit der Größe Größe und dem Adresstyp Typ zurück. Mögliche Adresstypen sind AF_INET und AF_INET6 (definiert in <sys/socket.h>). Das Argument Adr 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.

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;        /* Rechner-Adresstyp */
        int    h_length;          /* Größe 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 Nullzeiger.

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

h_length
    Die Größe der Adresse in Byte.

h_addr_list
    Ein Feld von Zeigern auf Netzwerkadressen für den Rechner (in der Netzwerk-Bytereihenfolge), gefolgt von einem Nullzeiger.

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 Nullzeiger 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
    Rechner-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-Unsicher race:hostbyname env locale
gethostbyaddr() | Multithread-Fähigkeit | MT-Unsicher race:hostbyaddr env locale
sethostent(), endhostent(), gethostent_r() | Multithread-Fähigkeit | MT-Unsicher race:hostent env locale
herror(), hstrerror() | Multithread-Fähigkeit | MT-Sicher
gethostent() | Multithread-Fähigkeit | MT-Unsicher race:hostent race:hostentbuf env locale
gethostbyname2() | Multithread-Fähigkeit | MT-Unsicher race:hostbyname2 env locale
gethostbyaddr_r(), gethostbyname_r(), gethostbyname2_r() | Multithread-Fähigkeit | MT-Sicher env locale

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.

STANDARDS

sethostent()
endhostent()
gethostent()
    POSIX.1-2008.

gethostent_r()
    GNU.

Andere:
    Keine.

GESCHICHTE

sethostent()
endhostent()
gethostent()
    POSIX.1-2001.

gethostbyname()
gethostbyaddr()
h_errno
    Wurde in POSIX.1-2001 als veraltet markiert und in POSIX.1-2008 entfernt; stattdessen wird die Verwendung von getaddrinfo(3) und getnameinfo(3) empfohlen.

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 Größe ein int. Der Standard SUSv2 ist fehlerhaft und weist dem Argument Größe 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 zu socklen_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 Rechner-Datenbank zurückgeben sollte. Bei der Verwendung von DNS/BIND ergibt das nicht viel Sinn, aber es kann sinnvoll sein, wenn die Rechner-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 Puffer der Größe Puffgröße bereit. Nach dem Aufruf zeigt bei Erfolg ergebnis auf das Ergebnis. Im Falle eines Fehlers oder wenn kein Eintrag gefunden wird, ist ergebnis 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 Puffer 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)

ÜBERSETZUNG
Die deutsche Übersetzung dieser Handbuchseite wurde von Martin Eberhard Schauer <Martin.E.Schauer@gmx.de>, Helge Kreutzmann <debian@helgefjell.de> und Mario Blättermann <mario.blaettermann@gmail.com> erstellt.

Diese Übersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 (https://www.gnu.org/licenses/gpl-3.0.html) 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 die Mailingliste der Übersetzer: debian-l10n-german@lists.debian.org.