<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation"> <title>gethostbyaddr()--Get Host Information for IP Address</title> <!-- Begin Header Records ========================================== --> <!-- All rights reserved. Licensed Materials Property of IBM --> <!-- US Government Users Restricted Rights --> <!-- Use, duplication or disclosure restricted by --> <!-- GSA ADP Schedule Contract with IBM Corp. --> <!-- Change History: --> <!-- Unix8 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 --> <!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 --> <!-- Edited by Kersten Feb 02 --> <link rel="stylesheet" type="text/css" href="../rzahg/ic.css"> </head> <body> <!--End Header Records --> <!-- Java sync-link --> <script type="text/javascript" language="Javascript" src="../rzahg/synch.js"> </script> <a name="Top_Of_Page"></a> <h2>gethostbyaddr()--Get Host Information for IP Address</h2> <div class="box" style="width: 70%;"> <br> BSD 4.3 Syntax<br> <pre> #include <netdb.h> struct hostent *gethostbyaddr(char *<em>host_address</em>, int <em>address_length</em>, int <em>address_type</em>) </pre> <br> Service Program Name: QSOSRV2<br> <!-- iddvc RMBR --> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Threadsafe: No; see <a href="#USAGE_NOTES">Usage Notes</a>.<br> <!-- iddvc RMBR --> <br> </div> <br> <div class="box" style="width: 70%;"> <br> <a href="_xopen_source.htm">UNIX 98 Compatible Syntax</a><br> <pre> #define _XOPEN_SOURCE 520 #include <netdb.h> struct hostent *gethostbyaddr(const void *<em>host_address</em>, socklen_t <em>address_length</em>, int <em>address_type</em>) </pre> <br> Service Program Name: QSOSRV2<br> <!-- iddvc RMBR --> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Threadsafe: No; see <a href="#USAGE_NOTES">Usage Notes</a>.<br> <!-- iddvc RMBR --> <br> </div> <br> <p>The <em>gethostbyaddr()</em> function is used to retrieve information about a host.</p> <p>There are two versions of the API, as shown above. The base i5/OS API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the UNIX 98 compatible interface with the <a href="_xopen_source.htm">_XOPEN_SOURCE</a> macro.</p> <br> <h3>Parameters</h3> <dl> <dt><strong>host_address</strong></dt> <dd>(Input) The pointer to a structure of type <strong>in_addr</strong> that contains the address of the host for which information is to be retrieved.<br> <br> </dd> <dt><strong>address_length</strong></dt> <dd>(Input) The length of the <em>host_address</em>.<br> <br> </dd> <dt><strong>address_type</strong></dt> <dd>(Input) The domain type of the host address. <samp>AF_INET</samp> is the only value for this parameter that is supported.</dd> </dl> <br> <h3>Authorities</h3> <p>No authorization is required.</p> <br> <h3>Return Value</h3> <p><em>gethostbyaddr()</em> returns a pointer. Possible values are:</p> <ul> <li>NULL (unsuccessful)<br> <br> </li> <li>p (successful), where p is a pointer to <strong>struct hostent</strong>, defined in <strong><netdb.h></strong>.</li> </ul> <pre> struct hostent { char *h_name; char **h_aliases; int h_addrtype; int h_length; char **h_addr_list; }; #define h_addr h_addr_list[0] </pre> <p><em>h_name</em> points to the character string that contains the name of the host. <em>h_aliases</em> is a pointer to a NULL-terminated list of pointers, each of which points to a character string that represents an alternative name for the host. <em>h_addrtype</em> contains the address type of the host (for example, <samp>AF_INET</samp>). <em>h_length</em> contains the address length. <em>h_addr_list</em> is a pointer to a NULL-terminated list of pointers, each of which points to a network address for the host, in network byte order. Note that the array of address pointers points to structures of type <strong>in_addr</strong> defined in <strong><netinet/in.h></strong>.</p> <h3>Error Conditions</h3> <p>When <em>gethostbyaddr()</em> fails, <em>h_errno</em> (defined in <strong><netdb.h></strong>) can be set to one of the following:</p> <dl> <dt><em>[HOST_NOT_FOUND]</em></dt> <dd><p>The host name specified by the <em>host_address</em> parameter was not found.</p></dd> <dt><em>[NO_DATA]</em></dt> <dd><p>The host name is a valid name, but there is no corresponding IP address.</p></dd> <dt><em>[NO_RECOVERY]</em></dt> <dd><p>An unrecoverable error has occurred.</p></dd> <dt><em>[TRY_AGAIN]</em></dt> <dd><p>The local server did not receive a response from an authoritative server. An attempt at a later time may succeed.</p></dd> </dl> <br> <br> <h3><a name="USAGE_NOTES">Usage Notes</a></h3> <ol> <li>The iSeries Navigator or the following CL commands can be used to access the host database file:<br> <br> <ul> <li>ADDTCPHTE (Add TCP/IP Host Table Entry)<br> <br> </li> <li>RMVTCPHTE (Remove TCP/IP Host Table Entry)<br> <br> </li> <li>CHGTCPHTE (Change TCP/IP Host Table Entry)<br> <br> </li> <li>RNMTCPHTE (Rename TCP/IP Host Table Entry)<br> <br> </li> <li>MRGTCPHT (Merge TCP/IP Host Tables)</li> </ul> <br> <br> </li> <li>The pointer returned by <em>gethostbyaddr()</em> points to static storage that is overwritten on subsequent calls to the <em>gethostbyaddr()</em>, <em>gethostbyname()</em>, or <em>gethostent()</em> functions.<br> <br> </li> <li>There are two sources from which host information can be obtained: the domain name server, and the host database file. The path taken depends on whether an IP address is configured for a name server using the iSeries Navigator or option 12, Change TCP/IP domain information, on the Configure TCP/IP (CFGTCP) menu. <p>Note: A person with a UNIX background would expect this information to exist in a file known as <strong>/etc/resolv.conf</strong>. If the IP address is found (indicating that the local network is a domain network), the <em>gethostbyaddr()</em> function attempts to query the domain name server for information about a host. If the query fails, the information is obtained from the host database file. If the name server IP address is not found (indicating that local network is a flat network), the host database file is used to obtain the host information.</p> </li> <li>When host information is retrieved from the host database file, the opened file is only closed if a <em>sethostent()</em> with a nonzero parameter value was not previously done.<br> <br> </li> <li>If a <em>sethostent()</em> with a nonzero parameter value was previously done, <em>gethostbyaddr()</em>, when obtaining host information from the domain name server, communicates with the domain name server over a connection-oriented transport service (for example, TCP). Otherwise, <em>gethostbyaddr()</em> uses a connectionless transport service (for example, UDP).<br> <br> </li> <li>If the host information is obtained from the domain name server, the information is returned in the default coded character set identifier (CCSID) currently in effect for the job. (The default CCSID is the same as the job CCSID unless 65535 is requested, in which case the default CCSID is set based on the language ID of the job. See <a href= "../nls/rbagsglobalmain.htm">globalization</a> for more information.) If the host information is retrieved from the host database file, the default CCSID of the job is not used. To request translation of the host information when it is retrieved from the host database file, you must use a job CCSID of something other than 65535.<br> <br> </li> <li>Address families are defined in <strong><sys/socket.h></strong>, and the <strong>in_addr</strong> structure is defined in <strong><netinet/in.h></strong>.<br> <br> </li> <li>Do not use the <em>gethostbyaddr()</em> function in a multithreaded environment. See the multithread alternative <em>gethostbyaddr_r()</em> function.<br> <br> </li> <li>When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the <em>gethostbyaddr()</em> API is mapped to <em>qso_gethostbyaddr98()</em>.</li> </ol> <br> <h3>Related Information</h3> <ul> <li><a href="_xopen_source.htm">_XOPEN_SOURCE</a>--Using _XOPEN_SOURCE for the UNIX 98 compatible interface<br> <br> </li> <li><a href="hstrerror.htm">hstrerror()</a>--Retrieve Resolver Error Message<br> <br> </li> <li><a href="reshostalias.htm">res_hostalias()</a>--Retrieve the host alias<br> <br> </li> <li><a href="ghostnm.htm">gethostbyname()</a>--Get Host Information for Host Name<br> <br> </li> <li><a href="ghostnt.htm">gethostent()</a>--Get Next Entry from Host Database<br> <br> </li> <li><a href="shostnt.htm">sethostent()</a>--Open Host Database<br> <br> </li> <li><a href="ehostnt.htm">endhostent()</a>--Close Host Database</li> </ul> <br> <hr> API introduced: V3R1 <hr> <center> <table cellpadding="2" cellspacing="2"> <tr align="center"> <td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href= "unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a> </td> </tr> </table> </center> </body> </html>