gethostbyname 関数 (winsock.h)

[アーティクル]
03/15/2023

gethostbyname 関数は、ホストデータベースからホスト名に対応するホスト情報を取得します。

メモgethostbyname 関数は、getaddrinfo 関数の導入によって非推奨になりました。 Windows ソケット 2 アプリケーションを作成する開発者には、gethostbyname ではなく getaddrinfo 関数を使用するように求める必要があります。

構文

hostent * gethostbyname(
  const char *name
);

パラメーター

name

TBD

戻り値

エラーが発生しない場合、 gethostbyname は上記のホスト型構造体へのポインターを返します。それ以外の場合は null ポインターを返し、 WSAGetLastError を呼び出すことで特定のエラー番号を取得できます。

エラーコード	意味
WSANOTINITIALIZED	この関数を使用する前に、WSAStartup 呼び出しが正常に行われる必要があります。
WSAENETDOWN	ネットワークサブシステムが失敗しました。
WSAHOST_NOT_FOUND	権限のある応答ホストが見つかりません。
WSATRY_AGAIN	認証されていないホストが見つからないか、サーバーの障害。
WSANO_RECOVERY	回復不可能なエラーが発生しました。
WSANO_DATA	要求された名前は有効ですが、要求された種類のデータが見つかりませんでした。このエラーは、 name パラメーターに IPv6 アドレスまたは無効な IPv4 アドレスの文字列表現が含まれている場合にも返されます。このエラーは、 name パラメーターに、特定のプロトコル (IP ホスト名など) に対して検証された名前文字列が含まれていることを意味するように解釈しないでください。 Winsock では複数の名前サービスプロバイダーがサポートされているため、1 つの名前が 1 つのプロバイダーに対して有効であり、別のプロバイダーでは受け入れられない可能性があります。
WSAEINPROGRESS	ブロックしている Windows ソケット 1.1 呼び出しが進行中であるか、サービスプロバイダーがコールバック関数を処理しています。
WSAEFAULT	name パラメーターは、ユーザーアドレス空間の有効な部分ではありません。
WSAEINTR	ブロックしている Windows ソケット 1.1 呼び出しが WSACancelBlockingCall によって取り消されました。

注釈

gethostbyname 関数は、ホスト型構造体 (Windows ソケットによって割り当てられた構造体) へのポインターを返します。 hostent 構造体には、name パラメーターで指定されたホストが正常に検索された結果が含まれます。

name パラメーターで指定されたホストに IPv4 アドレスと IPv6 アドレスの両方がある場合は、IPv4 アドレスのみが返されます。 gethostbyname 関数は、name パラメーターの IPv4 アドレスのみを返すことができます。ホストの IPv6 アドレスが必要な場合、またはホストの IPv4 アドレスと IPv6 アドレスの両方が必要な場合は、 getaddrinfo 関数と関連する addrinfo 構造体を使用する必要があります。

name パラメーターが空の文字列を指している場合、または name が NULL の場合、返される文字列は、成功した gethostname 関数呼び出し (ローカルコンピューターの標準ホスト名) によって返される文字列と同じです。

name パラメーターに有効な IPv4 アドレスの文字列表現が含まれている場合は、文字列を表すバイナリ IPv4 アドレスがホスト型構造体で返されます。 ホスト型構造体の h_name メンバーには、IPv4 アドレスの文字列表現が含まれており、h_addr_listにはバイナリ IPv4 アドレスが含まれています。 name パラメーターに IPv6 アドレスまたは無効な IPv4 アドレスの文字列表現が含まれている場合、gethostbyname 関数は失敗し、WSANO_DATAを返します。

gethostbyname 関数によって返されるホスト型構造体のメモリは、スレッドローカルストレージから Winsock DLL によって内部的に割り当てられます。スレッドで gethostbyaddr 関数または gethostbyname 関数が何回呼び出されても、1 つのホスト型構造体のみが割り当てられ、使用されます。同じスレッドの gethostbyname 関数または gethostbyaddr 関数に対して追加の呼び出しを行う場合は、返されたホスト型構造体をアプリケーションバッファーにコピーする必要があります。それ以外の場合、戻り値は、同じスレッドで後続の gethostbyname または gethostbyaddr 呼び出しによって上書きされます。返された ホスト型 構造体に割り当てられた内部メモリは、スレッドの終了時に Winsock DLL によって解放されます。

アプリケーションは、返されたホスト型構造体によって使用されるメモリを解放しようとしないでください。アプリケーションは、この構造を変更したり、そのコンポーネントを解放したりしないでください。さらに、この構造体のコピーはスレッドごとに 1 つだけ割り当てられるため、アプリケーションは 、gethostbyname または gethostbyaddr への他の関数呼び出しを発行する前に、必要な情報をコピーする必要があります。

gethostbyname 関数は、名前に渡されたパラメーターとして IP アドレス文字列を受け取り、ホスト名に解決することはできません。このような要求は、IPv4 アドレスの文字列表現または不明なホスト名が渡されたと正確に扱われます。アプリケーションでは、inet_addr を使用して IPv4 アドレス文字列をバイナリ IPv4 アドレスに変換し、別の関数 gethostbyaddr を使用して IPv4 アドレスをホスト名に解決できます。

メモgethostbyname 関数は、バッファーを渡す前に name パラメーターのサイズをチェックしません。不適切なサイズの名前パラメーターを使用すると、ヒープの破損が発生する可能性があります。

コード例

次の例では、 gethostbyname 関数の使用方法を示します。

#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: この関数は、Windows Phone 8 以降のWindows Phone ストアアプリでサポートされています。

Windows 8.1とWindows Server 2012 R2: この関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストアアプリでサポートされています。

要件

要件	値
サポートされている最小のクライアント	Windows 8.1、 Windows Vista [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows Server 2003 [デスクトップアプリのみ \| UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	winsock.h (Winsock2.h、Winsock.h を含む)
Library	Ws2_32.lib
[DLL]	Ws2_32.dll