gethostbyname(3) Library Functions Manual gethostbyname(3) BEZEICHNUNG gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, h_errno, herror, hstrerror, gethostbyaddr_r, gethostbyname2, gethostbyname2_r, gethostbyname_r, gethostent_r - ermittelt den Netzwerkeintrag fur einen Host BIBLIOTHEK Standard-C-Bibliothek (libc, -lc) UBERSICHT #include void sethostent(int offenhalten); void endhostent(void); [[veraltet]] extern int h_errno; [[veraltet]] struct hostent *gethostbyname(const char *name); [[veraltet]] struct hostent *gethostbyaddr(const void Adr[.len], socklen_t Lange, 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(struct hostent *restrict ret, char Puffer[restrict .Pufflan], size_t Pufflan, struct hostent **restrict ergebnis, int *restrict h_errnop); [[veraltet]] int gethostbyaddr_r(const void Adr[restrict .len], socklen_t Lange, int Typ, struct hostent *restrict ret, char buf[restrict .Pufflan], size_t Pufflan, struct hostent **restrict ergebnis, int *restrict h_errnop); [[veraltet]] int gethostbyname_r(const char *restrict name, struct hostent *restrict ret, char buf[restrict .Pufflan], size_t Pufflan, struct hostent **restrict ergebnis, int *restrict h_errnop); [[veraltet]] int gethostbyname2_r(const char *restrict name, int af, struct hostent *restrict ret, char buf[restrict .Pufflan], size_t Pufflan, 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 einschliesslich 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 fur Nameserveranfragen genutzt werden soll und dass die Verbindung fur die nachfolgenden Anfragen bestehen bleiben soll. Ansonsten werden fur Nameserveranfragen UDP-Datagramme benutzt. Die Funktion endhostent() beendet die Nutzung einer TCP-Verbindung fur Namerserveranfragen. Die Funktion gethostbyname() gibt eine Struktur vom Typ hostent fur den angegebenen Host name zuruck. 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-Aquivalent in das Feld h_addr_list[0] der zuruckgegebenen 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) fur das Dateiformat). Falls der name nicht mit einem Punkt endet, werden die aktuelle Domain und ihre ubergeordneten Domains durchsucht. Die Funktion gethostbyaddr() gibt fur die angegebene Adresse Adr eine Struktur vom Typ hostent mit der Lange Lange und dem Adresstyp Typ zuruck. Mogliche Adresstypen sind AF_INET und AF_INET6 (definiert in ). Das Argument Adr ist ein Zeiger auf eine Struktur, die vom Adresstyp abhangt, beispielsweise eine struct in_addr * (moglicherweise ermittelt durch einen Aufruf von inet_addr(3)) fur den Adresstyp AF_INET. Die (veraltete) Funktion herror() gibt die zum aktuellen Wert von h_errno gehorende Fehlermeldung auf stderr aus. Die (veraltete) Funktion hstrerror() ermittelt zu einer Fehlernummer (normalerweise h_errno) die zugehorige Zeichenkette mit der Fehlermeldung. Die durch gethostbyname() und gethostbyaddr() durchgefuhrten Domain-Name-Abfragen verlassen sich auf die konfigurierten Quellen des >>Name Service Switch<< (nsswitch.conf(5)) oder einen lokalen Name-Server (named(8)). Standardmassig werden die Quellen des >>Name Service Switch<< (nsswitch.conf(5)) abgefragt und, falls das fehlschlagt, 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 alter wurde das Schlusselwort 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 wie folgt definiert: struct hostent { char *h_name; /* offizieller Name des Rechners */ char **h_aliases; /* Aliasliste */ int h_addrtype; /* Host-Adresstyp */ int h_length; /* Lange der Adresse */ char **h_addr_list; /* Adressliste */ } #define h_addr h_addr_list[0] /* fur Abwartskompatibilitat */ 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 Lange der Adresse in Byte h_addr_list ein Feld von Zeigern auf Netzwerkadressen fur den Rechner (in der Netzwerk-Bytereihenfolge), gefolgt von einem Nullzeiger h_addr die erste Adresse in h_addr_list, fur Abwartskompatibilitat RUCKGABEWERT Die Funktionen gethostbyname() und gethostbyaddr() geben eine hostent-Struktur zuruck. Bei einem Fehler wird ein Nullzeiger zuruckgegeben. In diesem Fall enthalt die Variable h_errno die Fehlernummer. Falls der Zeiger von NULL verschieden ist, kann der Ruckgabewert 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 gultig aber verfugt uber keine IP-Adresse. Ein anderer Anfragetyp beim Nameserver fur diese Domain konnte eine Antwort liefern. Die Konstante NO_ADDRESS ist ein Synonym fur NO_DATA. NO_RECOVERY Ein nichtbehebbarer Nameserverfehler ist aufgetreten. TRY_AGAIN Beim massgebenden Nameserver ist ein vorubergehender Fehler aufgetreten. Versuchen Sie es spater noch einmal. DATEIEN /etc/host.conf Konfigurationsdatei des Resolvers (Namensaufloser) /etc/hosts Host-Datenbankdatei /etc/nsswitch.conf Konfigurationsdatei fur >>name service switch<< ATTRIBUTE Siehe attributes(7) fur eine Erlauterung der in diesem Abschnitt verwandten Ausdrucke. +-------------------+-------------------------+------------------------+ |Schnittstelle | Attribut | Wert | +-------------------+-------------------------+------------------------+ |gethostbyname() | Multithread-Fahigkeit | MT-Unsicher | | | | race:hostbyname env | | | | locale | +-------------------+-------------------------+------------------------+ |gethostbyaddr() | Multithread-Fahigkeit | MT-Unsicher | | | | race:hostbyaddr env | | | | locale | +-------------------+-------------------------+------------------------+ |sethostent(), | Multithread-Fahigkeit | MT-Unsicher | |endhostent(), | | race:hostent env | |gethostent_r() | | locale | +-------------------+-------------------------+------------------------+ |herror(), | Multithread-Fahigkeit | MT-Sicher | |hstrerror() | | | +-------------------+-------------------------+------------------------+ |gethostent() | Multithread-Fahigkeit | MT-Unsicher | | | | race:hostent | | | | race:hostentbuf env | | | | locale | +-------------------+-------------------------+------------------------+ |gethostbyname2() | Multithread-Fahigkeit | MT-Unsicher | | | | race:hostbyname2 env | | | | locale | +-------------------+-------------------------+------------------------+ |gethostbyaddr_r(), | Multithread-Fahigkeit | MT-Sicher 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 konnten. 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() konnen Zeiger auf statische Daten zuruckgeben, welche bei spateren Aufrufen uberschrieben werden konnten. Das Kopieren von struct hostent ist nicht ausreichend, weil sie Zeiger enthalt. Eine tiefe Kopie ist erforderlich. In der ursprunglichen BSD-Implementierung von gethostbyname() war das Argument Lange ein int. Der Standard SUSv2 ist fehlerhaft und weist dem Argument Lange von gethostbyaddr() den Typ size_t zu. (Das ist falsch, weil es int sein muss und das fur 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 fur gethostbyaddr() verwendet const char * als Datentyp fur das erste Argument. System V/POSIX-Erweiterung POSIX verlangt die Existenz der Funktion gethostent(), die den nachsten Eintrag in der Host-Datenbank zuruckgeben 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 fur Zeile gelesen werden kann. Auf vielen Systemen liest eine Routine mit diesem Namen aus der Datei /etc/hosts. Es kann sein, dass sie nur verfugbar ist, wenn die Bibliothek ohne DNS-Unterstutzung gebaut wurde. Die Glibc-Version ignoriert Ipv6-Eintrage. Diese Funktion ist nicht ablaufinvariant. Glibc stellt die ablaufinvariante Version gethostent_r() bereit. GNU-Erweiterungen Glibc2 enthalt auch gethostbyname2(), welche wie gethostbyname() arbeitet, ermoglicht aber die Vorgabe der Adressfamilie, zu der die Adresse gehoren 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 ausgefullt wird, und einen temporaren Arbeitspuffer Puffer der Grosse Pufflan 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. Zusatzlich zu den Fehlern, die von den nicht ablaufinvarianten Versionen dieser Funktionen zuruckgegeben werden:Diese Funktionen melden ERANGE, falls Puffer zu klein war. In diesem Fall sollte der Aufruf mit einem grosseren Puffer wiederholt werden. Die globale Variable h_errno wird nicht verandert, sondern die Adresse einer Variablen zur Speicherung von Fehlernummern wird in h_errnop ubergeben. 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) UBERSETZUNG Die deutsche Ubersetzung dieser Handbuchseite wurde von Martin Eberhard Schauer , Helge Kreutzmann und Mario Blattermann erstellt. Diese Ubersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezuglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG ubernommen. Wenn Sie Fehler in der Ubersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an die Mailingliste der Ubersetzer . Linux man-pages 6.06 31. Oktober 2023 gethostbyname(3)