gethostbyname-Funktion (winsock.h)

Artikel
03/04/2024

Die gethostbyname-Funktion ruft Hostinformationen ab, die einem Hostnamen entsprechen, aus einer Hostdatenbank.

Hinweis Die gethostbyname-Funktion wurde durch die Einführung der getaddrinfo-Funktion veraltet. Entwickler, die Windows Sockets 2-Anwendungen erstellen, werden dringend aufgefordert, die getaddrinfo-Funktion anstelle von gethostbyname zu verwenden.

Syntax

hostent * gethostbyname(
  const char *name
);

Parameter

name

TBD

Rückgabewert

Wenn kein Fehler auftritt, gibt gethostbyname einen Zeiger auf die oben beschriebene Hostentstruktur zurück. Andernfalls wird ein NULL-Zeiger zurückgegeben, und eine bestimmte Fehlernummer kann durch Aufrufen von WSAGetLastError abgerufen werden.

Fehlercode	Bedeutung
WSANOTINITIALISIERT	Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen.
WSAENETDOWN	Fehler beim Netzwerksubsystem.
WSAHOST_NOT_FOUND	Autorisierender Antworthost nicht gefunden.
WSATRY_AGAIN	Nicht autoritativer Host nicht gefunden, oder Serverfehler.
WSANO_RECOVERY	Ein nicht behebbarer Fehler ist aufgetreten.
WSANO_DATA	Der angeforderte Name ist gültig, es wurde jedoch keine Daten mit dem angeforderten Typ gefunden. Dieser Fehler wird auch zurückgegeben, wenn der Name-Parameter eine Zeichenfolgendarstellung einer IPv6-Adresse oder einer unzulässigen IPv4-Adresse enthält. Dieser Fehler sollte nicht so interpretiert werden, dass der name-Parameter eine Namenszeichenfolge enthält, die für ein bestimmtes Protokoll (z. B. einen IP-Hostnamen) überprüft wurde. Da Winsock mehrere Namensdienstanbieter unterstützt, kann ein Name möglicherweise für einen Anbieter gültig und von einem anderen Anbieter nicht akzeptiert werden.
WSAEINPROGRESS	Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet noch eine Rückruffunktion.
WSAEFAULT	Der Name-Parameter ist kein gültiger Teil des Benutzeradressraums.
WSAEINTR	Ein blockierender Windows Socket 1.1-Aufruf wurde über WSACancelBlockingCall abgebrochen.

Hinweise

Die gethostbyname-Funktion gibt einen Zeiger auf eine Hostentstruktur zurück– eine Struktur, die von Windows Sockets zugeordnet wird. Die hostent-Struktur enthält die Ergebnisse einer erfolgreichen Suche nach dem im name-Parameter angegebenen Host.

Wenn der im name-Parameter angegebene Host sowohl über IPv4- als auch über IPv6-Adressen verfügt, werden nur die IPv4-Adressen zurückgegeben. Die gethostbyname-Funktion kann nur IPv4-Adressen für den name-Parameter zurückgeben. Die getaddrinfo-Funktion und die zugehörige addrinfo-Struktur sollten verwendet werden, wenn IPv6-Adressen für den Host erforderlich sind oder wenn sowohl IPv4- als auch IPv6-Adressen für den Host erforderlich sind.

Wenn der name-Parameter auf eine leere Zeichenfolge zeigt oder der NameNULL ist, entspricht die zurückgegebene Zeichenfolge der Zeichenfolge, die von einem erfolgreichen Aufruf der gethostname-Funktion zurückgegeben wird (der Standardhostname für den lokalen Computer).

Wenn der name-Parameter eine Zeichenfolgendarstellung einer legalen IPv4-Adresse enthält, wird die binäre IPv4-Adresse, die die Zeichenfolge darstellt, in der Hostentstruktur zurückgegeben. Der h_name Member der Hostent-Struktur enthält die Zeichenfolgendarstellung der IPv4-Adresse und die h_addr_list die binäre IPv4-Adresse. Wenn der name-Parameter eine Zeichenfolgendarstellung einer IPv6-Adresse oder einer unzulässigen IPv4-Adresse enthält, schlägt die gethostbyname-Funktion fehl und gibt WSANO_DATA zurück.

Der Arbeitsspeicher für die hostent-Struktur , die von der gethostbyname-Funktion zurückgegeben wird, wird intern von der Winsock-DLL aus dem lokalen Threadspeicher zugeordnet. Es wird nur eine einzelne hostent-Struktur zugeordnet und verwendet, unabhängig davon, wie oft die Funktionen gethostbyaddr oder gethostbyname im Thread aufgerufen werden. Die zurückgegebene hostent-Struktur muss in einen Anwendungspuffer kopiert werden, wenn zusätzliche Aufrufe an die Funktionen gethostbyname oder gethostbyaddr im selben Thread ausgeführt werden sollen. Andernfalls wird der Rückgabewert durch nachfolgende gethostbyname - oder gethostbyaddr-Aufrufe im selben Thread überschrieben. Der für die zurückgegebene Hostent-Struktur zugeordnete interne Speicher wird von der Winsock-DLL freigegeben, wenn der Thread beendet wird.

Eine Anwendung sollte nicht versuchen, den von der zurückgegebenen Hostent-Struktur verwendeten Arbeitsspeicher freizugeben. Die Anwendung darf niemals versuchen, diese Struktur zu ändern oder ihre Komponenten frei zu geben. Darüber hinaus wird pro Thread nur eine Kopie dieser Struktur zugeordnet, sodass die Anwendung alle benötigten Informationen kopieren sollte, bevor sie andere Funktionsaufrufe für gethostbyname oder gethostbyaddr ausgibt .

Die gethostbyname-Funktion kann keine IP-Adresszeichenfolge als Parameter annehmen, der im Namen an sie übergeben wird, und sie in einen Hostnamen auflösen. Eine solche Anforderung wird genau so behandelt, wie eine Zeichenfolgendarstellung einer IPv4-Adresse oder eines unbekannten Hostnamens übergeben wurde. Eine Anwendung kann die inet_addr verwenden, um eine IPv4-Adresszeichenfolge in eine binäre IPv4-Adresse zu konvertieren, und dann eine andere Funktion, gethostbyaddr, verwenden, um die IPv4-Adresse in einen Hostnamen aufzulösen.

Hinweis Die gethostbyname-Funktion überprüft nicht die Größe des namensparameters , bevor der Puffer übergeben wird. Bei einem nicht ordnungsgemäß dimensionierten Namensparameter kann eine Heapbeschädigung auftreten.

Beispielcode

In den folgenden Beispielen wird die Verwendung der Gethostbyname-Funktion veranschaulicht.

#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
#include <windows.h>
#pragma comment(lib, "ws2_32.lib")

int main(int argc, char **argv)
{

    //-----------------------------------------
    // Declare and initialize variables
    WSADATA wsaData;
    int iResult;

    DWORD dwError;
    int i = 0;

    struct hostent *remoteHost;
    char *host_name;
    struct in_addr addr;

    char **pAlias;

    // Validate the parameters
    if (argc != 2) {
        printf("usage: %s hostname\n", argv[0]);
        printf("  to return the IP addresses for the host\n");
        printf("       %s www.contoso.com\n", argv[0]);
        printf(" or\n");
        printf("       %s IPv4string\n", argv[0]);
        printf("  to return an IPv4 binary address for an IPv4string\n");
        printf("       %s 127.0.0.1\n", argv[0]);
        return 1;
    }
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        printf("WSAStartup failed: %d\n", iResult);
        return 1;
    }

    host_name = argv[1];

    printf("Calling gethostbyname with %s\n", host_name);
    remoteHost = gethostbyname(host_name);
    
    if (remoteHost == NULL) {
        dwError = WSAGetLastError();
        if (dwError != 0) {
            if (dwError == WSAHOST_NOT_FOUND) {
                printf("Host not found\n");
                return 1;
            } else if (dwError == WSANO_DATA) {
                printf("No data record found\n");
                return 1;
            } else {
                printf("Function failed with error: %ld\n", dwError);
                return 1;
            }
        }
    } else {
        printf("Function returned:\n");
        printf("\tOfficial name: %s\n", remoteHost->h_name);
        for (pAlias = remoteHost->h_aliases; *pAlias != 0; pAlias++) {
            printf("\tAlternate name #%d: %s\n", ++i, *pAlias);
        }
        printf("\tAddress type: ");
        switch (remoteHost->h_addrtype) {
        case AF_INET:
            printf("AF_INET\n");
            break;
        case AF_NETBIOS:
            printf("AF_NETBIOS\n");
            break;
        default:
            printf(" %d\n", remoteHost->h_addrtype);
            break;
        }
        printf("\tAddress length: %d\n", remoteHost->h_length);

        i = 0;
        if (remoteHost->h_addrtype == AF_INET)
        {
            while (remoteHost->h_addr_list[i] != 0) {
                addr.s_addr = *(u_long *) remoteHost->h_addr_list[i++];
                printf("\tIP Address #%d: %s\n", i, inet_ntoa(addr));
            }
        }
        else if (remoteHost->h_addrtype == AF_NETBIOS)
        {   
            printf("NETBIOS address was returned\n");
        }   
    }

    return 0;
}

Windows Phone 8: Diese Funktion wird für Windows Phone Store-Apps ab Windows Phone 8 unterstützt.

Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8.1, Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winsock.h (einschließlich Winsock2.h, Winsock.h)
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll