res_init()--Initialize _res Structure


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

 void res_init(void)

  Service Program Name: QSOSRV2

  Default Public Authority: *USE

  Threadsafe: Yes

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_init() 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 IPv4 name server(s) configured by CHGTCPDMN at the time res_init() or res_ninit() was called. It does not contain any IPv6 name server(s) configured by CHGTCPDMN. nsaddr_list also does not contain any name server addresses dynamically added by other utilities such as SOCKS or a Point to Point (PPP) connection. By default, queries are first attempted using the (IPv4 and IPv6) CHGTCPDMN configuration and, if that fails, then using the dynamic addresses.

If an application changes the nsaddr_list entries it is effectively overriding the CHGTCPDMN configuration. Neither IPv4 nor IPv6 configured name servers will be used. However, the dynamic SOCKS/PPP name servers will still be used unless the application also sets the RES_NSADDRONLY option.

If an application does not change nsaddr_list, then it will be kept current with CHGTCPDMN configuration changes.



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 IBM® i 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 Do not query the name server addresses dynamically configured by SOCKS or Point to Point (PPP) connections. See nsaddr_list for information about CHGTCPDMN name server configuration.
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:

  2. The default initialization values can be overridden with environment 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.

    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


API introduced: V3R1

[ Back to top | UNIX-Type APIs | APIs by category ]