The
gethostbyname function retrieves host information corresponding to a host name from a host database.
Note The
gethostbyname function has been deprecated by the introduction of the
getaddrinfo function. Developers creating Windows Sockets 2 applications are urged to use the
getaddrinfo function instead of
gethostbyname.
Syntax
struct hostent* FAR gethostbyname(
__in const char *name
);
Parameters
- name [in]
-
A pointer to the null-terminated name of the host to resolve.
Return Value
If no error occurs,
gethostbyname returns a pointer to the
hostent structure described above. Otherwise, it returns a null pointer and a specific error number can be retrieved by calling
WSAGetLastError.
Remarks
The
gethostbyname function returns a pointer to a
hostent structure—a structure allocated by Windows Sockets. The
hostent structure contains the results of a successful search for the host specified in the name parameter.
The memory for the hostent structure returned by the gethostbyname function is allocated internally by the Winsock DLL from thread local storage. Only a single hostent structure is allocated and used, no matter how many times the gethostbyaddr
or gethostbyname functions are called on the thread. The returned hostent structure must be copied to an application buffer if additional calls are to be made to the gethostbyname or gethostbyaddr functions on the same thread. Otherwise, the return value will be overwritten by subsequent gethostbyname or gethostbyaddr
calls on the same thread. The internal memory allocated for the returned hostent structure is released by the Winsock DLL when the thread exits.
An application should not try to release the memory used by the returned hostent structure. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, so the application should copy any information it needs before issuing any other function calls to gethostbyname or gethostbyaddr
.
The
gethostbyname function cannot resolve IP address strings passed to it. Such a request is treated exactly as if an unknown host name were passed. Use
inet_addr to convert an IP address string to an actual IP address, then use another function,
gethostbyaddr, to obtain the contents of the
hostent structure.
If the name parameter points to an empty string or name is NULL, the returned string is the same as the string returned by a successful
gethostname function call (the standard host name for the local computer).
Note The gethostbyname function does not check the size of the name parameter before passing the buffer. With an improperly sized name parameter, heap corruption can occur.
Example Code
The following examples demonstrates the use of the gethostbyname function.
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
#include <windows.h>
#pragma comment(lib, "wininet.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 ipv4address\n", argv[0]);
printf(" or\n");
printf(" %s hostname\n", argv[0]);
printf(" to return the host\n");
printf(" %s 127.0.0.1\n", argv[0]);
printf(" to return the IP addresses for a host\n");
printf(" %s www.contoso.com\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];
// If the user input is an alpha name for the host, use gethostbyname()
// If not, get host by addr (assume IPv4)
if (isalpha(host_name[0])) { /* host address is a name */
printf("Calling gethostbyname with %s\n", host_name);
remoteHost = gethostbyname(host_name);
} else {
printf("Calling gethostbyaddr with %s\n", host_name);
addr.s_addr = inet_addr(host_name);
if (addr.s_addr == INADDR_NONE) {
printf("The IPv4 address entered must be a legal address\n");
return 1;
} else
remoteHost = gethostbyaddr((char *) &addr, 4, AF_INET);
}
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_INET6:
printf("AF_INET6\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;
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));
}
}
return 0;
}
Requirements
| Minimum supported client | Windows 2000 Professional |
|---|
| Minimum supported server | Windows 2000 Server |
|---|
| Header | Winsock2.h |
|---|
| Library | Ws2_32.lib |
|---|
| DLL | Ws2_32.dll |
|---|
See Also
- Winsock Reference
- Winsock Functions
- getaddrinfo
- gethostbyaddr
- gethostname
- WSAAsyncGetHostByName
- hostent
Send comments about this topic to Microsoft
Build date: 11/12/2009