MSDN Documentation

gethostbyname

The gethostbyname function retrieves the address of a host from a database. This function is deprecated.

Syntax

struct hostent *gethostbyname(
  const char *name
);
            

Parameters

name

A pointer to a NULL-terminated string that contains the name of the host for which to retrieve address information.

Return Value

If successful, gethostbyname returns a pointer to a hostent structure. If the host name is not found, or if an error occurs, gethostbyname returns NULL. An application should always check the return value for NULL to handle potential errors.

Remarks

The gethostbyname function retrieves host information from a name resolution database. The Winsock service provider for the NBP name resolution service is typically used.

The name can be an alias, a canonical name, or a combination of both.

The hostent structure contains an entry for the specified host name. The members of the hostent structure are:

hostent Structure

struct hostent {
    char    FAR * h_name;         // Official name of the host.
    char    FAR **h_aliases;      // Array of aliases for the host.
    int     h_addrtype;           // Type of the host's addresses (AF_INET for IPv4).
    int     h_length;             // Length, in bytes, of the host's addresses.
    char    FAR **h_addr_list;    // NULL-terminated array of network addresses for the host.
};
            

Members

• h_name: The official name of the host.
• h_aliases: An array of null-terminated strings, terminated by a null pointer, which are the aliases for the host.
• h_addrtype: The address type. The only supported address type is AF_INET.
• h_length: The length, in bytes, of the address. This will be 4 for AF_INET addresses.
• h_addr_list: A null-terminated array of pointers, each pointing to a buffer containing a network address for the host. The addresses are in network byte order.

An application should not free the memory pointed to by the returned hostent structure or any of its members. It should be treated as read-only.

Example

#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>

// Link with Ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")

int main(int argc, char **argv) {
    WSADATA wsaData;
    struct hostent *remoteHost;
    char *hostname;
    char **lpAlias;
    char **lpAddr;
    int i = 0;

    if (argc != 2) {
        fprintf(stderr, "usage: %s <hostname>\n", argv[0]);
        return 1;
    }

    hostname = argv[1];

    // Initialize Winsock
    if (WSAStartup(MAKEWORD(2, 2), &wsaData) != 0) {
        fprintf(stderr, "WSAStartup failed.\n");
        return 1;
    }

    printf("Calling gethostbyname for %s\n", hostname);

    // Get host information
    remoteHost = gethostbyname(hostname);

    if (remoteHost == NULL) {
        fprintf(stderr, "gethostbyname failed: %d\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }

    printf("Official name: %s\n", remoteHost->h_name);
    printf("Host address type: %s\n", (remoteHost->h_addrtype == AF_INET) ? "AF_INET" : "Other");
    printf("Address length: %d\n", remoteHost->h_length);

    // Print aliases
    lpAlias = remoteHost->h_aliases;
    if (*lpAlias) {
        printf("Aliases:\n");
        while (*lpAlias) {
            printf("  %s\n", *lpAlias);
            lpAlias++;
        }
    } else {
        printf("No aliases found.\n");
    }

    // Print IP addresses
    lpAddr = remoteHost->h_addr_list;
    if (*lpAddr) {
        printf("IP Addresses:\n");
        while (*lpAddr) {
            printf("  %s\n", inet_ntoa(*(struct in_addr *)*lpAddr));
            lpAddr++;
        }
    } else {
        printf("No IP addresses found.\n");
    }

    WSACleanup();
    return 0;
}