res_init()--Initialize _res Structure

 #include <sys/types.h>
 #include <netinet/in.h>
 #include <arpa/nameser.h>
 #include <resolv.h>

 void res_init(void)

The res_init() function is used to initialize the _res 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 _res structure.) Also, the default domain name and other components of the domain to search are put into the _res structure.

The _res structure is defined in <resolv.h>.

      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];
        };



      #define nsaddr nsaddr_list[0]

      extern struct state _res;

retrans

Time interval in seconds between retries. The default is received from QUSRSYS/QATOCTCPIP which is configured with the Change TCP/IP Domain (CHGTCPDMN) command

retry

Number of times to retransmit. The default is received from QUSRSYS/QATOCTCPIP which is configured with the Change TCP/IP Domain (CHGTCPDMN) command

options

Contains flag bits to indicate the different resolver options. The default is RES_DEFAULT

nscount

Number of name servers. res_ninit() sets the number of name servers to the number found in the database file. The maximum is 3

nsaddr_list

Contains the address(es) of the name server(s)

id

Current packet ID. The id is initialized to a random number

defdname

Default domain name or the search list

dnsrch

Contains the components of the search list. By default it points to components of defdname 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 dnsrch to point to it. Each component pointed to by an element of dnsrch must be NULL terminated.

sort_list

List of address/mask pairs that will be used to sort the results of a gethostbyname() or gethostbyname_r() operation

res_h_errno

Holds the last h_errno or errno set by the resolver for this context

ndots

Number of dots in a name that will trigger an absolute query instead of using the dnsrch

nsort

Number of elements in the sort_list array

state_data

Used internally by the resolver

reserved0,reserved1 and reserved

Fields are that set to zeros by res_ninit() or res_init(). If the res structure is manually initialized by a program, it also must set these structures to zeros.

nsaddr

Defined for backward compatibility

options

The value for the options is constructed by performing an OR operation on the following values:

RES_INIT	Indicates that the res structure has been initialized.
RES_AAONLY	Requests the answer be authoritative and not from a name server's cache.
RES_USEVC	Tells the resolver to use TCP instead of UDP.
RES_IGNTC	Tells the resolver to ignore truncation.
RES_RECURSE	Specifies that recursion is desired.
RES_DEFNAMES	Appends the default domain name to single label queries.
RES_STAYOPEN	Causes the TCP connection to remain open (used with RES_USEVC).
RES_DNSRCH	Searches using dnsrch.
RES_INSECURE1	Disables type 1 security. Type 1 security rejects responses that didn't come from one of the configured DNS servers.
RES_INSECURE2	Disables type 2 security. Type 2 security checks the question section of the reply to ensure it matches the original query sent.
RES_NOALIASES	Tells the resolver to ignore the HOSTALIASES environment variable.
RES_ROTATE	Tells the resolver to rotate through the list of DNS servers (nsaddr_list).
RES_NOCHECKNAME	Tells the resolver not to check host names in replies for disallowed characters such as underscore (_), non-ASCII, or control characters.
RES_KEEPTSIG	Stops the resolver from stripping TSIG records on replies.
RES_NOCACHE	Do not look in the resolver answer cache. Query the name server. The answer may still be locally cached.

The following four values are i5/OS specific.

RES_XINIT	Indicates that the extended portion of the res structure has been initialized.
RES_CP850	Use ASCII code page 850 and not ASCII code page 819.
RES_RETRYTCP	Retry with a TCP connection if the UDP connection fails for any reason.
RES_NSADDRONLY	Only use the list of addresses in nsaddr. There may be a separate SOCKS DNS configured that would normally be used.
RES_DEFAULT	This is the default. Causes an OR operation on the RES_RECURSE, RES_DEFNAMES, RES_DNSRCH values.

Authorities:

No authorization is required.

Return Value

None.

Error Conditions

res_init() can set errno to the following:

[EINVAL]

_res appears to have been previously initialized but the reserved field is not set to zeros.

[EUNKNOWN]

res_init() was unable to retrieve the DNS server configuration.

Usage Notes

1. If no entry was configured with Change TCP/IP Domain (CHGTCPDMN), then res_init() does the following:
   • Calls gethostname() 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.
     
     
   • Calls getservbyname() to get the port number.
     
     
   • Uses hard-coded defaults for retrans, retry and ndots (5, 4 and 1 respectively).
   
   
   
2. The default initialization values can be overridden with enviroment variables. Note: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.
   • LOCALDOMAIN

     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.

   • 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:
     • 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.
       
     • 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.
       
     • ATTEMPTS:n sets the number of queries the resolver will send to a given nameserver before giving up and trying the next listed nameserver.
       
     • 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.
       
     • 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.
     
     
   • QIBM_BIND_RESOLVER_FLAGS

     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:
     ADDENVVAR ENVVAR(QIBM_BIND_RESOLVER_FLAGS) VALUE('RES_NOCHECKNAME NOT_RES_ROTATE')
     or
     ADDENVVAR ENVVAR(QIBM_BIND_RESOLVER_FLAGS) VALUE('+RES_NOCHECKNAME -RES_ROTATE')

   • QIBM_BIND_RESOLVER_SORTLIST

     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)

   Note: Environment variables are only checked after a successful call to res_init() or res_ninit(). 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.

3. res_init() is called by res_send(), res_mkquery(), res_search(), and res_query() if they detect the _res structure has not been initialized (RES_INIT option). res_init() 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 res_init() directly. Then before the call to res_send(), set the RES_USEVC bit in the options flag. Other things in the _res structure, like the number of retries or time interval between retries, can be changed in a like manner.
   
   
4. If the server protocol configured with Change TCP/IP Domain (CHGTCPDMN) is set to TCP, then res_init() sets the RES_USEVC bit in the options field of the _res structure.
   
   
5. In a thread-enabled environment the _res structure is shared among all threads within a process.

Related Information

• hstrerror()--Retrieve Resolver Error Message
  
  
• res_ninit()--Initialize res Structure
  
  
• res_hostalias()--Retrieve the host alias
  
  
• res_close()--Close Socket and Reset _res Structure
  
  
• res_mkquery()--Place Domain Query in Buffer
  
  
• res_query()--Send Domain Query
  
  
• res_search()--Search for Domain Name
  
  
• res_send()--Send Buffered Domain Query
  
  
• res_xlate()--Translate DNS Packets