Provided by: manpages-de-dev_2.16-1_all 
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)