592 lines
16 KiB
HTML
592 lines
16 KiB
HTML
<!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>res_init()--Initialize _res Structure</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. -->
|
|
<!-- 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 -->
|
|
<!--End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<a name="Top_Of_Page"></a>
|
|
<!-- Java sync-link -->
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
|
</script>
|
|
|
|
<h2>res_init()--Initialize _res Structure</h2>
|
|
|
|
<div class="box" style="width: 60%;">
|
|
<br>
|
|
Syntax<br>
|
|
<pre>
|
|
#include <sys/types.h>
|
|
#include <netinet/in.h>
|
|
#include <arpa/nameser.h>
|
|
#include <resolv.h>
|
|
|
|
void res_init(void)
|
|
</pre>
|
|
|
|
<br>
|
|
Service Program Name: QSOSRV2<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The <em>res_init()</em> function is used to initialize the
|
|
<strong>_res</strong> structure for name resolution. Two bits are set in the
|
|
structure to indicate that it has been initialized. (These are the RES_INIT and
|
|
RES_XINIT bits in the options field of the <strong>_res</strong> structure.)
|
|
Also, the default domain name and other components of the domain to search are
|
|
put into the <strong>_res</strong> structure.</p>
|
|
|
|
<p>The <strong>_res</strong> structure is defined in
|
|
<strong><resolv.h></strong>.</p>
|
|
|
|
<pre>
|
|
struct state {
|
|
int retrans;
|
|
int retry;
|
|
long options;
|
|
int nscount;
|
|
struct sockaddr_in nsaddr_list[MAXNS];
|
|
u_short id;
|
|
char defdname[MAXDNAME];
|
|
char reserved0[1];
|
|
char reserved1[13];
|
|
char *dnsrch[MAXDNSRCH+1];
|
|
|
|
/* Extended state structure begins here.*/
|
|
struct {
|
|
struct in_addr addr;
|
|
uint mask;
|
|
} sort_list[MAXRESOLVSORT];
|
|
int res_h_errno;
|
|
int extended_error;
|
|
unsigned ndots:4;
|
|
unsigned nsort:4;
|
|
char state_data[27];
|
|
int internal_use[4];
|
|
char reserved[444];
|
|
};
|
|
<br>
|
|
|
|
#define nsaddr nsaddr_list[0]
|
|
|
|
extern struct state _res;
|
|
</pre>
|
|
|
|
<dl>
|
|
<dt><em>retrans</em></dt>
|
|
|
|
<dd>Time interval in seconds between retries. The default is received from
|
|
QUSRSYS/QATOCTCPIP which is configured with the Change TCP/IP Domain
|
|
(CHGTCPDMN) command<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><em>retry</em></dt>
|
|
|
|
<dd>Number of times to retransmit. The default is received from
|
|
QUSRSYS/QATOCTCPIP which is configured with the Change TCP/IP Domain
|
|
(CHGTCPDMN) command<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><em>options</em></dt>
|
|
|
|
<dd>Contains flag bits to indicate the different resolver options. The default
|
|
is <em>RES_DEFAULT</em><br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><em>nscount</em></dt>
|
|
|
|
<dd>Number of name servers. <em>res_ninit()</em> sets the number of name
|
|
servers to the number found in the database file. The maximum is 3<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><em>nsaddr_list</em></dt>
|
|
|
|
<dd>Contains the address(es) of the name server(s)<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><em>id</em></dt>
|
|
|
|
<dd>Current packet ID. The id is initialized to a random number<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><em>defdname</em></dt>
|
|
|
|
<dd>Default domain name or the search list<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><em>dnsrch</em></dt>
|
|
|
|
<dd>Contains the components of the search list. By default it points to
|
|
components of <em>defdname</em> which contains the local domain or the
|
|
configured search list. However a program may allocate separate storage for a
|
|
customized search list and set the elements of <em>dnsrch</em> to point to it.
|
|
Each component pointed to by an element of <em>dnsrch</em> must be NULL
|
|
terminated.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><em>sort_list</em></dt>
|
|
|
|
<dd>List of address/mask pairs that will be used to sort the results of a
|
|
<em>gethostbyname()</em> or <em>gethostbyname_r()</em> operation<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><em>res_h_errno</em></dt>
|
|
|
|
<dd>Holds the last <em>h_errno</em> or <em>errno</em> set by the resolver for
|
|
this context<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><em>ndots</em></dt>
|
|
|
|
<dd>Number of dots in a name that will trigger an absolute query instead of
|
|
using the <em>dnsrch</em><br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><em>nsort</em></dt>
|
|
|
|
<dd>Number of elements in the <em>sort_list</em> array<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><em>state_data</em></dt>
|
|
|
|
<dd>Used internally by the resolver<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><em>reserved0</em>,<em>reserved1</em> and <em>reserved</em></dt>
|
|
|
|
<dd>Fields are that set to zeros by <em>res_ninit()</em> or
|
|
<em>res_init()</em>. If the <strong>res</strong> structure is manually
|
|
initialized by a program, it also must set these structures to zeros.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><em>nsaddr</em></dt>
|
|
|
|
<dd>Defined for backward compatibility<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><em>options</em></dt>
|
|
|
|
<dd>The value for the <em>options</em> is constructed by performing an OR
|
|
operation on the following values:<br>
|
|
<br>
|
|
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="20 80" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_INIT</em></td>
|
|
<td align="left" valign="top">Indicates that the <strong>res</strong> structure
|
|
has been initialized.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_AAONLY</em></td>
|
|
<td align="left" valign="top">Requests the answer be authoritative and not from
|
|
a name server's cache.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_USEVC</em></td>
|
|
<td align="left" valign="top">Tells the resolver to use TCP instead of UDP.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_IGNTC</em></td>
|
|
<td align="left" valign="top">Tells the resolver to ignore truncation.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_RECURSE</em></td>
|
|
<td align="left" valign="top">Specifies that recursion is desired.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_DEFNAMES</em></td>
|
|
<td align="left" valign="top">Appends the default domain name to single label
|
|
queries.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_STAYOPEN</em></td>
|
|
<td align="left" valign="top">Causes the TCP connection to remain open (used
|
|
with RES_USEVC).<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_DNSRCH</em></td>
|
|
<td align="left" valign="top">Searches using <em>dnsrch</em>.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_INSECURE1</em></td>
|
|
<td align="left" valign="top">Disables type 1 security. Type 1 security rejects
|
|
responses that didn't come from one of the configured DNS servers.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_INSECURE2</em></td>
|
|
<td align="left" valign="top">Disables type 2 security. Type 2 security checks
|
|
the question section of the reply to ensure it matches the original query
|
|
sent.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_NOALIASES</em></td>
|
|
<td align="left" valign="top">Tells the resolver to ignore the HOSTALIASES
|
|
environment variable.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_ROTATE</em></td>
|
|
<td align="left" valign="top">Tells the resolver to rotate through the list of
|
|
DNS servers (<em>nsaddr_list</em>).<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_NOCHECKNAME</em></td>
|
|
<td align="left" valign="top">Tells the resolver not to check host names in
|
|
replies for disallowed characters such as underscore (_), non-ASCII, or control
|
|
characters.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_KEEPTSIG</em></td>
|
|
<td align="left" valign="top">Stops the resolver from stripping TSIG records on
|
|
replies.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_NOCACHE</em></td>
|
|
<td align="left" valign="top">Do not look in the resolver answer cache. Query
|
|
the name server. The answer may still be locally cached.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The following four values are i5/OS specific.</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="20 80" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_XINIT</em></td>
|
|
<td align="left" valign="top">Indicates that the extended portion of the
|
|
<strong>res</strong> structure has been initialized.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_CP850</em></td>
|
|
<td align="left" valign="top">Use ASCII code page 850 and not ASCII code page
|
|
819.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_RETRYTCP</em></td>
|
|
<td align="left" valign="top">Retry with a TCP connection if the UDP connection
|
|
fails for any reason.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_NSADDRONLY</em></td>
|
|
<td align="left" valign="top">Only use the list of addresses in
|
|
<em>nsaddr</em>. There may be a separate SOCKS DNS configured that would
|
|
normally be used.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RES_DEFAULT</em></td>
|
|
<td align="left" valign="top">This is the default. Causes an OR operation on
|
|
the RES_RECURSE, RES_DEFNAMES, RES_DNSRCH values.</td>
|
|
</tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Authorities:</h3>
|
|
|
|
<p>No authorization is required.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Return Value</h3>
|
|
|
|
<p>None.</p>
|
|
|
|
<br>
|
|
<h3>Error Conditions</h3>
|
|
<p><em>res_init()</em> can set <em>errno</em> to the following:</p>
|
|
<dl>
|
|
|
|
<dt><em>[EINVAL]</em></dt>
|
|
<dd><p><strong>_res</strong> appears to have been
|
|
previously initialized but the reserved field is not set to zeros.</p></dd>
|
|
|
|
|
|
<dt><em>[EUNKNOWN]</em></dt>
|
|
<dd><p><em>res_init()</em> was unable to retrieve the
|
|
DNS server configuration.</p></dd>
|
|
|
|
</dl>
|
|
|
|
<br>
|
|
<br>
|
|
<h3>Usage Notes</h3>
|
|
|
|
<ol>
|
|
<li>If no entry was configured with Change TCP/IP Domain (CHGTCPDMN), then
|
|
<em>res_init()</em> does the following:
|
|
|
|
<ul>
|
|
<li>Calls <em>gethostname()</em> to get the default domain name. The default
|
|
domain name in this case is the host name minus the first component of the
|
|
name. For example, if the host name is ABC.RCHLAND.IBM.COM, the default name is
|
|
RCHLAND.IBM.COM.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Calls <em>getservbyname()</em> to get the port number.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Uses hard-coded defaults for <em>retrans</em>, <em>retry</em> and
|
|
<em>ndots</em> (5, 4 and 1 respectively).</li>
|
|
</ul>
|
|
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The default initialization values can be overridden with enviroment
|
|
variables. <em>Note:</em>The name of the environment variable must be
|
|
uppercased. The string value may be mixed case. Japanese systems using CCSID
|
|
290 should use uppercase characters and numbers only in both environment
|
|
variables names and values.
|
|
|
|
<ul>
|
|
<li>LOCALDOMAIN
|
|
|
|
<p>The configured search list (struct state.defdname and struct state.dnsrch)
|
|
can be overridden by setting the environment variable LOCALDOMAIN to a
|
|
space-separated list of up to 6 search domains with a total of 256 characters
|
|
(including spaces). If a search list is specified, the default local domain is
|
|
not used on queries.</p>
|
|
</li>
|
|
|
|
<li>RES_OPTIONS allows certain internal resolver variables to be modified. The
|
|
environment variable can be set to one or more of the following space-separated
|
|
options:
|
|
|
|
<ul>
|
|
<li>NDOTS:n sets a threshold for the number of dots which must appear in a name
|
|
given to res_query() before an initial absolute query will be made. The default
|
|
for n is ``1'', meaning that if there are any dots in a name, the name will be
|
|
tried first as an absolute name before any search list elements are appended to
|
|
it.<br>
|
|
</li>
|
|
|
|
<li>TIMEOUT:n sets the amount of time (in seconds) the resolver will wait for a
|
|
response from a remote name server before giving up and retrying the query.<br>
|
|
</li>
|
|
|
|
<li>ATTEMPTS:n sets the number of queries the resolver will send to a given
|
|
nameserver before giving up and trying the next listed nameserver.<br>
|
|
</li>
|
|
|
|
<li>ROTATE sets RES_ROTATE in _res.options , which causes round robin selection
|
|
of nameservers from among those listed. This has the effect of spreading the
|
|
query load among all listed servers, rather than having all clients try the
|
|
first listed server first every time.<br>
|
|
</li>
|
|
|
|
<li>NO-CHECK-NAMES sets RES_NOCHECKNAME in _res.options , which disables the
|
|
modern BIND checking of incoming host names and mail names for invalid
|
|
characters such as underscore (_), non-ASCII, or control characters.</li>
|
|
</ul>
|
|
|
|
<br>
|
|
</li>
|
|
|
|
<li>QIBM_BIND_RESOLVER_FLAGS
|
|
|
|
<p>The RES_DEFAULT options (struct state.options) and system configured values
|
|
(Change TCP/IP Domain - CHGTCPDMN) can be overridden by setting the environment
|
|
variable QIBM_BIND_RESOLVER_FLAGS to a space separated list of resolver option
|
|
flags. The state.options structure will be initialized normally, using
|
|
RES_DEFAULT, OPTIONS environment values and CHGTCPDMN configured values. Then
|
|
this environment varible will be used to override those defaults. The flags
|
|
named in this environment variable may be prepended with a '+', '-' or 'NOT_'
|
|
to set ('+') or reset ('-','NOT_') the value. For example, to turn on
|
|
RES_NOCHECKNAME and turn off RES_ROTATE:<br>
|
|
ADDENVVAR ENVVAR(QIBM_BIND_RESOLVER_FLAGS) VALUE('RES_NOCHECKNAME
|
|
NOT_RES_ROTATE')<br>
|
|
or<br>
|
|
ADDENVVAR ENVVAR(QIBM_BIND_RESOLVER_FLAGS) VALUE('+RES_NOCHECKNAME
|
|
-RES_ROTATE')</p>
|
|
</li>
|
|
|
|
<li>QIBM_BIND_RESOLVER_SORTLIST
|
|
|
|
<p>A sort list (struct state.sort_list) can be configured by setting the
|
|
environment variable QIBM_BIND_RESOLVER_SORTLIST to a space-separated list of
|
|
up to 10 ip addresses/mask pairs in dotted decimal format
|
|
(9.5.9.0/255.255.255.0)</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p><em>Note:</em> Environment variables are only checked after a successful
|
|
call to <em>res_init()</em> or <em>res_ninit()</em>. So if the structure has
|
|
been manually initialized, environment variables are ignored. Also note that
|
|
the structure is only initialized once so later changes to the environment
|
|
variables will be ignored.</p>
|
|
</li>
|
|
|
|
<li><em>res_init()</em> is called by <em>res_send()</em>,
|
|
<em>res_mkquery()</em>, <em>res_search()</em>, and <em>res_query()</em> if they
|
|
detect the <strong>_res</strong> structure has not been initialized (RES_INIT
|
|
option). <em>res_init()</em> can also be called directly to change the defaults
|
|
and hence, change the behavior of one of the above routines. For example, if
|
|
you want to use TCP rather than attempt UDP first, simply call
|
|
<em>res_init()</em> directly. Then before the call to <em>res_send()</em>, set
|
|
the RES_USEVC bit in the options flag. Other things in the
|
|
<strong>_res</strong> structure, like the number of retries or time interval
|
|
between retries, can be changed in a like manner.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>If the server protocol configured with Change TCP/IP Domain (CHGTCPDMN) is
|
|
set to TCP, then <em>res_init()</em> sets the RES_USEVC bit in the options
|
|
field of the <strong>_res</strong> structure.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>In a thread-enabled environment the <strong>_res</strong> structure is
|
|
shared among all threads within a process.</li>
|
|
</ol>
|
|
|
|
<br>
|
|
<h3>Related Information</h3>
|
|
|
|
<ul>
|
|
<li><a href="hstrerror.htm">hstrerror()</a>--Retrieve Resolver Error
|
|
Message<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="resninit.htm">res_ninit()</a>--Initialize res Structure<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="reshostalias.htm">res_hostalias()</a>--Retrieve the host alias<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="resclo.htm">res_close()</a>--Close Socket and Reset _res
|
|
Structure<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="resmkq.htm">res_mkquery()</a>--Place Domain Query in Buffer<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="resqry.htm">res_query()</a>--Send Domain Query<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="ressch.htm">res_search()</a>--Search for Domain Name<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="ressnd.htm">res_send()</a>--Send Buffered Domain Query<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="resxlt.htm">res_xlate()</a>--Translate DNS Packets</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>
|
|
|