The Pascal compiler company

• Pascal Compiler
• Web Programming
• About Irie Tools

Description

The gethostbyaddr function returns information about a host identified by address. The host information is returned in a structure of type hostent. This structure is allocated by the WinSock2 library, and your program should not attempt to modify or de-allocate, the structure or any of its components.

Only one copy of the hostent structure is allocated per calling thread, and since Irie Pascal programs only have one thread, there will be only one copy of this structure allocated for your program. As a result, you should copy any host information you need from the structure before calling any other Windows Sockets functions.

Declaration

The system include file WinSock2.inc contains the following declaration for the hostent and p_hostent types and the gethostbyaddr function:

 hostent = packed record
  h_name : address;
  h_aliases : address;
  h_addrtype : shortint;
  h_length : shortint;
  h_addr_list : address;
 end;

 p_hostent = ^hostent;

 function gethostbyaddr(addr : address; len, typ : integer) : address;
  external dll='ws2_32.dll';

Arguments

The First Argument

The first argument passed to the gethostbyaddr function is the operating system address of the buffer containing the address of the host you want to get information about. The address stored in the buffer is not stored as a string, it is stored as a numeric value in in network byte order. The type of this argument is the built-in type address, so you must use the built-in function addr to get the operating system address of the buffer.

If you have the address of a host, as a null-terminated string, and you want to get information about that host then you should do the following:

1. Use the inet_addr function to convert the address, represented as a string into an address, represented in a numeric format.
2. Use the gethostbyaddr function to get the host information.

The Second Argument

The second argument passed to the gethostbyaddr function is the length of the host address in the buffer pointed to be the first argument.

The Third Argument

The third argument passed to the gethostbyaddr function is the type of the host address in the buffer pointed to be the first argument.

Return Values

The gethostbyaddr function returns a pointer to the hostent structure that contains the host information, if the call is successful. If the call fails then the value nil is returned, and in this case you can use the WSAGetLastError function to retrieve a code that identifies the error that caused the call to fail.

Example

The following procedure was taken from one of the sample programs distributed with Irie Pascal and shows one way to use the gethostbyaddr function.

 //PUPOSE: Given the IP address of a host perform a reverse DNS lookup.
 //    1. strIPAddress - contains the name of the host
 procedure ReverseDNSLookUp(strIPAddress : cstring);
 var
  IPAddress : in_addr;
  pHostEnt : p_hostent;
 begin
  IPAddress := inet_addr(addr(strIPAddress));
  if IPAddress = INADDR_NONE then
   writeln('Invalid IP address')
  else
   begin
    pHostEnt := gethostbyaddr(addr(IPAddress), sizeof(IPAddress), AF_INET);
    if pHostEnt = nil then
     writeln('Can not find address ''', hex(IPAddress), '''')
    else
     DisplayHostEntInfo(pHostEnt);
   end;
 end;

The procedure DisplayHostEntInfo is defined by the sample program and displays the host information stored in the hostent structure. See the gethostbyname function for the actual DisplayHostEntInfo procedure.

Reference Information

The authoritative source of information about the WinSock2 library is the Microsoft Developers Network (MSDN). You can access the MSDN on the Microsoft website at msdn.microsoft.com.