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:

The following four values are IBM® i specific.


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 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.
    • 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 variable 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


API introduced: V3R1

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