gethostbyname 함수(winsock.h)

아티클
08/27/2023

gethostbyname 함수는 호스트 데이터베이스에서 호스트 이름에 해당하는 호스트 정보를 검색합니다.

참고gethostbyname 함수는 getaddrinfo 함수를 도입하여 더 이상 사용되지 않습니다. Windows Sockets 2 애플리케이션을 만드는 개발자는 gethostbyname 대신 getaddrinfo 함수를 사용해야 합니다.

구문

hostent * gethostbyname(
  const char *name
);

매개 변수

name

TBD

반환 값

오류가 발생하지 않으면 gethostbyname 은 위에서 설명한 호스트 구조체에 대한 포인터를 반환합니다. 그렇지 않으면 null 포인터를 반환하고 WSAGetLastError를 호출하여 특정 오류 번호를 검색할 수 있습니다.

오류 코드	의미
WSANOTINITIALISED	이 함수를 사용하기 전에 성공적인 WSAStartup 호출이 발생해야 합니다.
WSAENETDOWN	네트워크 하위 시스템이 실패했습니다.
WSAHOST_NOT_FOUND	신뢰할 수 있는 응답 호스트를 찾을 수 없습니다.
WSATRY_AGAIN	인증되지 않은 호스트를 찾을 수 없거나 서버 오류가 발생했습니다.
WSANO_RECOVERY	복구할 수 없는 오류가 발생했습니다.
WSANO_DATA	요청한 이름은 유효하지만 요청한 형식의 데이터를 찾을 수 없습니다. 이름 매개 변수에 IPv6 주소 또는 잘못된 IPv4 주소의 문자열 표현이 포함된 경우에도 이 오류가 반환됩니다. 이 오류는 name 매개 변수에 특정 프로토콜(예: IP 호스트 이름)에 대해 유효성이 검사된 이름 문자열이 포함되어 있음을 의미하는 것으로 해석되어서는 안 됩니다. Winsock은 여러 이름 서비스 공급자를 지원하므로 한 공급자에 대해 이름이 유효하고 다른 공급자가 허용하지 않을 수 있습니다.
WSAEINPROGRESS	차단 Windows 소켓 1.1 호출이 진행 중이거나 서비스 공급자가 여전히 콜백 함수를 처리하고 있습니다.
WSAEFAULT	이름 매개 변수가 사용자 주소 공간의 유효한 부분이 아닙니다.
WSAEINTR	WSACancelBlockingCall을 통해 차단 Windows 소켓 1.1 호출이 취소되었습니다.

설명

gethostbyname 함수는 호스트 구조체(Windows Sockets에서 할당한 구조체)에 대한 포인터를 반환합니다. hostent 구조에는 이름 매개 변수에 지정된 호스트에 대한 성공적인 검색 결과가 포함됩니다.

이름 매개 변수에 지정된 호스트에 IPv4 및 IPv6 주소가 모두 있는 경우 IPv4 주소만 반환됩니다. gethostbyname 함수는 name 매개 변수에 대한 IPv4 주소만 반환할 수 있습니다. 호스트에 대한 IPv6 주소가 필요하거나 호스트에 대한 IPv4 및 IPv6 주소가 모두 필요한 경우 getaddrinfo 함수 및 연결된 addrinfo 구조를 사용해야 합니다.

name 매개 변수가 빈 문자열을 가리키거나 이름이NULL인 경우 반환된 문자열은 gethostname 함수 호출(로컬 컴퓨터의 표준 호스트 이름)에서 반환된 문자열과 동일합니다.

name 매개 변수에 법적 IPv4 주소의 문자열 표현이 포함된 경우 문자열을 나타내는 이진 IPv4 주소가 호스트 구조로 반환됩니다. 호스트 구조의 h_name 멤버는 IPv4 주소의 문자열 표현을 포함하고 h_addr_list 이진 IPv4 주소를 포함합니다. name 매개 변수에 IPv6 주소 또는 잘못된 IPv4 주소의 문자열 표현이 포함된 경우 gethostbyname 함수가 실패하고 WSANO_DATA 반환합니다.

gethostbyname 함수에서 반환된 호스트 구조체의 메모리는 스레드 로컬 스토리지의 Winsock DLL에 의해 내부적으로 할당됩니다. 스레드에서 gethostbyaddr 또는 gethostbyname 함수가 호출되는 횟수에 관계없이 단일 호스트 구조만 할당되고 사용됩니다. 동일한 스레드의 gethostbyname 또는 gethostbyaddr 함수에 대해 추가 호출을 수행해야 하는 경우 반환된 호스트 구조체를 애플리케이션 버퍼에 복사해야 합니다. 그렇지 않으면 반환 값은 동일한 스레드에서 후속 gethostbyname 또는 gethostbyaddr 호출에 의해 덮어씁니다. 반환된 호스트 구조에 할당된 내부 메모리는 스레드가 종료될 때 Winsock DLL에서 해제됩니다.

애플리케이션은 반환된 호스트 구조에서 사용하는 메모리를 해제하려고 시도해서는 안 됩니다 . 애플리케이션은 이 구조를 수정하거나 해당 구성 요소를 해제하려고 시도해서는 안 됩니다. 또한 이 구조체의 복사본은 스레드당 하나만 할당되므로 애플리케이션은 gethostbyname 또는 gethostbyaddr 에 대한 다른 함수 호출을 실행하기 전에 필요한 정보를 복사해야 합니다.

gethostbyname 함수는 IP 주소 문자열을 이름에 전달된 매개 변수로 사용하여 호스트 이름으로 resolve 수 없습니다. 이러한 요청은 정확히 IPv4 주소의 문자열 표현으로 처리되거나 알 수 없는 호스트 이름이 전달되었습니다. 애플리케이션은 inet_addr 사용하여 IPv4 주소 문자열을 이진 IPv4 주소로 변환한 다음 다른 함수 gethostbyaddr를 사용하여 IPv4 주소를 호스트 이름으로 resolve 수 있습니다.

참고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 포함)
라이브러리	Ws2_32.lib
DLL	Ws2_32.dll