RESOLVER(3) FreeBSD Library Functions Manual RESOLVER(3) NNAAMMEE rreess__nniinniitt, rreess__oouurrsseerrvveerr__pp, ffpp__rreessssttaatt, rreess__hhoossttaalliiaass, rreess__ppqquueerryy, rreess__nnqquueerryy, rreess__nnsseeaarrcchh, rreess__nnqquueerryyddoommaaiinn, rreess__nnmmkkqquueerryy, rreess__nnsseenndd, rreess__nnuuppddaattee, rreess__nnmmkkuuppddaattee, rreess__nncclloossee, rreess__nnsseennddssiiggnneedd, rreess__ffiinnddzzoonneeccuutt, rreess__ggeettsseerrvveerrss, rreess__sseettsseerrvveerrss, rreess__nnddeessttrrooyy, ddnn__ccoommpp, ddnn__eexxppaanndd, hhssttrreerrrroorr, rreess__iinniitt, rreess__iissoouurrsseerrvveerr, ffpp__nnqquueerryy, pp__qquueerryy, hhoossttaalliiaass, rreess__qquueerryy, rreess__sseeaarrcchh, rreess__qquueerryyddoommaaiinn, rreess__mmkkqquueerryy, rreess__sseenndd, rreess__uuppddaattee, rreess__cclloossee, hheerrrroorr -- resolver routines SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> _t_y_p_e_d_e_f _s_t_r_u_c_t _____r_e_s___s_t_a_t_e _*_r_e_s___s_t_a_t_e; _i_n_t rreess__nniinniitt(_r_e_s___s_t_a_t_e _s_t_a_t_p); _i_n_t rreess__oouurrsseerrvveerr__pp(_c_o_n_s_t _r_e_s___s_t_a_t_e _s_t_a_t_p, _c_o_n_s_t _s_t_r_u_c_t _s_o_c_k_a_d_d_r___i_n _*_a_d_d_r); _v_o_i_d ffpp__rreessssttaatt(_c_o_n_s_t _r_e_s___s_t_a_t_e _s_t_a_t_p, _F_I_L_E _*_f_p); _c_o_n_s_t _c_h_a_r _* rreess__hhoossttaalliiaass(_c_o_n_s_t _r_e_s___s_t_a_t_e _s_t_a_t_p, _c_o_n_s_t _c_h_a_r _*_n_a_m_e, _c_h_a_r _*_b_u_f, _s_i_z_e___t _b_u_f_l_e_n); _i_n_t rreess__ppqquueerryy(_c_o_n_s_t _r_e_s___s_t_a_t_e _s_t_a_t_p, _c_o_n_s_t _u___c_h_a_r _*_m_s_g, _i_n_t _m_s_g_l_e_n, _F_I_L_E _*_f_p); _i_n_t rreess__nnqquueerryy(_r_e_s___s_t_a_t_e _s_t_a_t_p, _c_o_n_s_t _c_h_a_r _*_d_n_a_m_e, _i_n_t _c_l_a_s_s, _i_n_t _t_y_p_e, _u___c_h_a_r _*_a_n_s_w_e_r, _i_n_t _a_n_s_l_e_n); _i_n_t rreess__nnsseeaarrcchh(_r_e_s___s_t_a_t_e _s_t_a_t_p, _c_o_n_s_t _c_h_a_r _*_d_n_a_m_e, _i_n_t _c_l_a_s_s, _i_n_t _t_y_p_e, _u___c_h_a_r _* _a_n_s_w_e_r, _i_n_t _a_n_s_l_e_n); _i_n_t rreess__nnqquueerryyddoommaaiinn(_r_e_s___s_t_a_t_e _s_t_a_t_p, _c_o_n_s_t _c_h_a_r _*_n_a_m_e, _c_o_n_s_t _c_h_a_r _*_d_o_m_a_i_n, _i_n_t _c_l_a_s_s, _i_n_t _t_y_p_e, _u___c_h_a_r _*_a_n_s_w_e_r, _i_n_t _a_n_s_l_e_n); _i_n_t rreess__nnmmkkqquueerryy(_r_e_s___s_t_a_t_e _s_t_a_t_p, _i_n_t _o_p, _c_o_n_s_t _c_h_a_r _*_d_n_a_m_e, _i_n_t _c_l_a_s_s, _i_n_t _t_y_p_e, _c_o_n_s_t _u___c_h_a_r _*_d_a_t_a, _i_n_t _d_a_t_a_l_e_n, _c_o_n_s_t _u___c_h_a_r _*_n_e_w_r_r, _u___c_h_a_r _*_b_u_f, _i_n_t _b_u_f_l_e_n); _i_n_t rreess__nnsseenndd(_r_e_s___s_t_a_t_e _s_t_a_t_p, _c_o_n_s_t _u___c_h_a_r _*_m_s_g, _i_n_t _m_s_g_l_e_n, _u___c_h_a_r _*_a_n_s_w_e_r, _i_n_t _a_n_s_l_e_n); _i_n_t rreess__nnuuppddaattee(_r_e_s___s_t_a_t_e _s_t_a_t_p, _n_s___u_p_d_r_e_c _*_r_r_e_c_p___i_n); _i_n_t rreess__nnmmkkuuppddaattee(_r_e_s___s_t_a_t_e _s_t_a_t_p, _n_s___u_p_d_r_e_c _*_r_r_e_c_p___i_n, _u___c_h_a_r _*_b_u_f, _i_n_t _b_u_f_l_e_n); _v_o_i_d rreess__nncclloossee(_r_e_s___s_t_a_t_e _s_t_a_t_p); _i_n_t rreess__nnsseennddssiiggnneedd(_r_e_s___s_t_a_t_e _s_t_a_t_p, _c_o_n_s_t _u___c_h_a_r _*_m_s_g, _i_n_t _m_s_g_l_e_n, _n_s___t_s_i_g___k_e_y _*_k_e_y, _u___c_h_a_r _*_a_n_s_w_e_r, _i_n_t _a_n_s_l_e_n); _i_n_t rreess__ffiinnddzzoonneeccuutt(_r_e_s___s_t_a_t_e _s_t_a_t_p, _c_o_n_s_t _c_h_a_r _*_d_n_a_m_e, _n_s___c_l_a_s_s _c_l_a_s_s, _i_n_t _o_p_t_i_o_n_s, _c_h_a_r _*_z_n_a_m_e, _s_i_z_e___t _z_s_i_z_e, _s_t_r_u_c_t _i_n___a_d_d_r _*_a_d_d_r_s, _i_n_t _n_a_d_d_r_s); _i_n_t rreess__ggeettsseerrvveerrss(_r_e_s___s_t_a_t_e _s_t_a_t_p, _u_n_i_o_n _r_e_s___s_o_c_k_a_d_d_r___u_n_i_o_n _*_s_e_t, _i_n_t _c_n_t); _v_o_i_d rreess__sseettsseerrvveerrss(_r_e_s___s_t_a_t_e _s_t_a_t_p, _c_o_n_s_t _u_n_i_o_n _r_e_s___s_o_c_k_a_d_d_r___u_n_i_o_n _*_s_e_t, _i_n_t _c_n_t); _v_o_i_d rreess__nnddeessttrrooyy(_r_e_s___s_t_a_t_e _s_t_a_t_p); _i_n_t ddnn__ccoommpp(_c_o_n_s_t _c_h_a_r _*_e_x_p___d_n, _u___c_h_a_r _*_c_o_m_p___d_n, _i_n_t _l_e_n_g_t_h, _u___c_h_a_r _*_*_d_n_p_t_r_s, _u___c_h_a_r _*_*_l_a_s_t_d_n_p_t_r); _i_n_t ddnn__eexxppaanndd(_c_o_n_s_t _u___c_h_a_r _*_m_s_g, _c_o_n_s_t _u___c_h_a_r _*_e_o_m_o_r_i_g, _c_o_n_s_t _u___c_h_a_r _*_c_o_m_p___d_n, _c_h_a_r _*_e_x_p___d_n, _i_n_t _l_e_n_g_t_h); _c_o_n_s_t _c_h_a_r _* hhssttrreerrrroorr(_i_n_t _e_r_r); DDEEPPRREECCAATTEEDD ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> ##iinncclluuddee <> _i_n_t rreess__iinniitt(_v_o_i_d); _i_n_t rreess__iissoouurrsseerrvveerr(_c_o_n_s_t _s_t_r_u_c_t _s_o_c_k_a_d_d_r___i_n _*_a_d_d_r); _i_n_t ffpp__nnqquueerryy(_c_o_n_s_t _u___c_h_a_r _*_m_s_g, _i_n_t _m_s_g_l_e_n, _F_I_L_E _*_f_p); _v_o_i_d pp__qquueerryy(_c_o_n_s_t _u___c_h_a_r _*_m_s_g, _F_I_L_E _*_f_p); _c_o_n_s_t _c_h_a_r _* hhoossttaalliiaass(_c_o_n_s_t _c_h_a_r _*_n_a_m_e); _i_n_t rreess__qquueerryy(_c_o_n_s_t _c_h_a_r _*_d_n_a_m_e, _i_n_t _c_l_a_s_s, _i_n_t _t_y_p_e, _u___c_h_a_r _*_a_n_s_w_e_r, _i_n_t _a_n_s_l_e_n); _i_n_t rreess__sseeaarrcchh(_c_o_n_s_t _c_h_a_r _*_d_n_a_m_e, _i_n_t _c_l_a_s_s, _i_n_t _t_y_p_e, _u___c_h_a_r _*_a_n_s_w_e_r, _i_n_t _a_n_s_l_e_n); _i_n_t rreess__qquueerryyddoommaaiinn(_c_o_n_s_t _c_h_a_r _*_n_a_m_e, _c_o_n_s_t _c_h_a_r _*_d_o_m_a_i_n, _i_n_t _c_l_a_s_s, _i_n_t _t_y_p_e, _u___c_h_a_r _*_a_n_s_w_e_r, _i_n_t _a_n_s_l_e_n); _i_n_t rreess__mmkkqquueerryy(_i_n_t _o_p, _c_o_n_s_t _c_h_a_r _*_d_n_a_m_e, _i_n_t _c_l_a_s_s, _i_n_t _t_y_p_e, _c_o_n_s_t _c_h_a_r _*_d_a_t_a, _i_n_t _d_a_t_a_l_e_n, _s_t_r_u_c_t _r_r_e_c _*_n_e_w_r_r, _u___c_h_a_r _*_b_u_f, _i_n_t _b_u_f_l_e_n); _i_n_t rreess__sseenndd(_c_o_n_s_t _u___c_h_a_r _*_m_s_g, _i_n_t _m_s_g_l_e_n, _u___c_h_a_r _*_a_n_s_w_e_r, _i_n_t _a_n_s_l_e_n); _i_n_t rreess__uuppddaattee(_n_s___u_p_d_r_e_c _*_r_r_e_c_p___i_n); _v_o_i_d rreess__cclloossee(_v_o_i_d); _v_o_i_d hheerrrroorr(_c_o_n_s_t _c_h_a_r _*_s); DDEESSCCRRIIPPTTIIOONN These routines are used for making, sending and interpreting query and reply messages with Internet domain name servers. State information is kept in _s_t_a_t_p and is used to control the behavior of these functions. _s_t_a_t_p should be set to all zeros prior to the first call to any of these functions. The functions rreess__iinniitt(), rreess__iissoouurrsseerrvveerr(), ffpp__nnqquueerryy(), pp__qquueerryy(), hhoossttaalliiaass(), rreess__qquueerryy(), rreess__sseeaarrcchh(), rreess__qquueerryyddoommaaiinn(), rreess__mmkkqquueerryy(), rreess__sseenndd(), rreess__uuppddaattee(), rreess__cclloossee() and hheerrrroorr() are deprecated and are supplied for compatability with old source code. They use global config- uration and state information that is kept in the structure ___r_e_s rather than that referenced through _s_t_a_t_p. Most of the values in _s_t_a_t_p and ___r_e_s are initialized on the first call to rreess__nniinniitt() / rreess__iinniitt() to reasonable defaults and can be ignored. Options stored in _s_t_a_t_p_-_>_o_p_t_i_o_n_s / ___r_e_s_._o_p_t_i_o_n_s are defined in _r_e_s_o_l_v_._h and are as follows. Options are stored as a simple bit mask containing the bitwise ``OR'' of the options enabled. RES_INIT True if the initial name server address and default domain name are initialized (i.e., rreess__nniinniitt() / rreess__iinniitt() has been called). RES_DEBUG Print debugging messages. RES_AAONLY Accept authoritative answers only. Should continue until it finds an authoritative answer or finds an error. Currently this is not implemented. RES_USEVC Use TCP connections for queries instead of UDP datagrams. RES_STAYOPEN Used with RES_USEVC to keep the TCP connection open between queries. This is useful only in programs that regularly do many queries. UDP should be the normal mode used. RES_IGNTC Ignore truncation errors, i.e., don't retry with TCP. RES_RECURSE Set the recursion-desired bit in queries. This is the default. (rreess__nnsseenndd() / rreess__sseenndd() does not do iterative queries and expects the name server to handle recursion.) RES_DEFNAMES If set, rreess__nnsseeaarrcchh() / rreess__sseeaarrcchh() will append the default domain name to single-component names (those that do not contain a dot). This option is enabled by default. RES_DNSRCH If this option is set, rreess__nnsseeaarrcchh() / rreess__sseeaarrcchh() will search for host names in the current domain and in parent domains; see hostname(7). This is used by the standard host lookup routine gethostbyname(3). This option is enabled by default. RES_NOALIASES This option turns off the user level aliasing feature controlled by the HOSTALIASES environment variable. Network daemons should set this option. RES_USE_INET6 This option causes gethostbyname(3) to look for AAAA records before looking for A records if none are found. RES_ROTATE This options causes the rreess__nnsseenndd() / rreess__sseenndd() to rotate the list of nameservers in _s_t_a_t_p_-_>_n_s_a_d_d_r___l_i_s_t / ___r_e_s_._n_s_a_d_d_r___l_i_s_t. RES_KEEPTSIG This option causes rreess__nnsseennddssiiggnneedd() to leave the message unchanged after TSIG verification; otherwise the TSIG record would be removed and the header updated. RES_NOTLDQUERY This option causes rreess__nnsseeaarrcchh() to not attempt to resolve a unqualified name as if it were a top level domain (TLD). This option can cause problems if the site has "localhost" as a TLD rather than having localhost on one or more elements of the search list. This option has no effect if neither RES_DEFNAMES or RES_DNSRCH is set. The rreess__nniinniitt() / rreess__iinniitt() routine reads the configuration file (if any; see resolver(5)) to get the default domain name, search list and the Internet address of the local name server(s). If no server is config- ured, the host running the resolver is tried. The current domain name is defined by the hostname if not specified in the configuration file; it can be overridden by the environment variable LOCALDOMAIN. This environ- ment variable may contain several blank-separated tokens if you wish to override the ``search list'' on a per-process basis. This is similar to the sseeaarrcchh command in the configuration file. Another environment vari- able (``RES_OPTIONS'') can be set to override certain internal resolver options which are otherwise set by changing fields in the _s_t_a_t_p / ___r_e_s structure or are inherited from the configuration file's ooppttiioonnss command. The syntax of the ``RES_OPTIONS'' environment variable is explained in resolver(5). Initialization normally occurs on the first call to one of the other resolver routines. The memory referred to by _s_t_a_t_p must be set to all zeros prior to the first call to rreess__nniinniitt(). rreess__nnddeessttrrooyy() should be call to free memory allocated by rreess__nniinniitt() after last use. The rreess__nnqquueerryy() / rreess__qquueerryy() functions provides interfaces to the server query mechanism. They constructs a query, sends it to the local server, awaits a response, and makes preliminary checks on the reply. The query requests information of the specified _t_y_p_e and _c_l_a_s_s for the specified fully-qualified domain name _d_n_a_m_e. The reply message is left in the _a_n_s_w_e_r buffer with length _a_n_s_l_e_n supplied by the caller. rreess__nnqquueerryy() / rreess__qquueerryy() return -1 on error or the length of the answer. The rreess__nnsseeaarrcchh() / rreess__sseeaarrcchh() routines make a query and awaits a response like rreess__nnqquueerryy() / rreess__qquueerryy(), but in addition, it implements the default and search rules controlled by the RES_DEFNAMES and RES_DNSRCH options. It returns the length of the first successful reply which is stored in _a_n_s_w_e_r or -1 on error. The remaining routines are lower-level routines used by rreess__nnqquueerryy() / rreess__qquueerryy(). The rreess__nnmmkkqquueerryy() / rreess__mmkkqquueerryy() functions constructs a standard query message and places it in _b_u_f. It returns the size of the query, or -1 if the query is larger than _b_u_f_l_e_n. The query type _o_p is usually QUERY, but can be any of the query types defined in _<_a_r_p_a_/_n_a_m_e_s_e_r_._h_>. The domain name for the query is given by _d_n_a_m_e. _N_e_w_r_r is currently unused but is intended for making update messages. The rreess__nnsseenndd() / rreess__sseenndd() / rreess__nnsseennddssiiggnneedd() routines sends a pre- formatted query and returns an answer. It will call rreess__nniinniitt() / rreess__iinniitt() if RES_INIT is not set, send the query to the local name server, and handle timeouts and retries. Additionally, rreess__nnsseennddssiiggnneedd() will use TSIG signatures to add authentication to the query and verify the response. In this case, only one nameserver will be contacted. The length of the reply message is returned, or -1 if there were errors. rreess__nnqquueerryy() / rreess__qquueerryy(), rreess__nnsseeaarrcchh() / rreess__sseeaarrcchh() and rreess__nnsseenndd() / rreess__sseenndd() return a length that may be bigger than _a_n_s_l_e_n. In that case the query should be retried with a bigger buffer. NOTE the answer to the second query may be larger still so supplying a buffer that bigger that the answer returned by the previous query is recommended. _a_n_s_w_e_r MUST be big enough to receive a maximum UDP response from the server or parts of the answer will be silently discarded. The default maximum UDP response size is 512 bytes. The function rreess__oouurrsseerrvveerr__pp() returns true when _i_n_p is one of the servers in _s_t_a_t_p_-_>_n_s_a_d_d_r___l_i_s_t / ___r_e_s_._n_s_a_d_d_r___l_i_s_t. The functions ffpp__nnqquueerryy() / pp__qquueerryy() print out the query and any answer in _m_s_g on _f_p. pp__qquueerryy() is equivalent to ffpp__nnqquueerryy() with _m_s_g_l_e_n set to 512. The function ffpp__rreessssttaatt() prints out the active flag bits in _s_t_a_t_p_-_>_o_p_t_i_o_n_s preceeded by the text ";; res options:" on _f_i_l_e. The functions rreess__hhoossttaalliiaass() / hhoossttaalliiaass() lookup up name in the file referred to by the HOSTALIASES files return a fully qualified hostname if found or NULL if not found or an error occurred. rreess__hhoossttaalliiaass() uses _b_u_f to store the result in, hhoossttaalliiaass() uses a static buffer. The functions rreess__ggeettsseerrvveerrss() and rreess__sseettsseerrvveerrss() are used to get and set the list of server to be queried. The functions rreess__nnuuppddaattee() / rreess__uuppddaattee() take a list of ns_updrec _r_r_e_c_p___i_n. Identifies the containing zone for each record and groups the records according to containing zone maintaining in zone order then sends and update request to the servers for these zones. The number of zones updated is returned or -1 on error. Note that rreess__nnuuppddaattee() will perform TSIG authenticated dynamic update operations if the key is not NULL. The function rreess__ffiinnddzzoonneeccuutt() discovers the closest enclosing zone cut for a specified domain name, and finds the IP addresses of the zone's master servers. The functions rreess__nnmmkkuuppddaattee() / rreess__mmkkuuppddaattee() take a linked list of ns_updrec _r_r_e_c_p___i_n and construct a UPDATE message in _b_u_f. rreess__nnmmkkuuppddaattee() / rreess__mmkkuuppddaattee() return the length of the constructed message on no error or one of the following error values. -1 An error occurred parsing _r_r_e_c_p___i_n. -2 The buffer _b_u_f was too small. -3 The first record was not a zone section or there was a section order problem. The section order is S_ZONE, S_PREREQ and S_UPDATE. -4 A number overflow occurred. -5 Unknown operation or no records. The functions rreess__nncclloossee() / rreess__cclloossee() close any open files referenced through _s_t_a_t_p / ___r_e_s. The function rreess__nnddeessttrrooyy() calls rreess__nncclloossee() then frees any memory allocated by rreess__nniinniitt(). The ddnn__ccoommpp() function compresses the domain name _e_x_p___d_n and stores it in _c_o_m_p___d_n. The size of the compressed name is returned or -1 if there were errors. The size of the array pointed to by _c_o_m_p___d_n is given by _l_e_n_g_t_h. The compression uses an array of pointers _d_n_p_t_r_s to previously-compressed names in the current message. The first pointer points to to the begin- ning of the message and the list ends with NULL. The limit to the array is specified by _l_a_s_t_d_n_p_t_r. A side effect of ddnn__ccoommpp() is to update the list of pointers for labels inserted into the message as the name is com- pressed. If _d_n_p_t_r is NULL, names are not compressed. If _l_a_s_t_d_n_p_t_r is NULL, the list of labels is not updated. The ddnn__eexxppaanndd() entry expands the compressed domain name _c_o_m_p___d_n to a full domain name. The compressed name is contained in a query or reply message; _m_s_g is a pointer to the beginning of the message. _e_o_m_o_r_i_g is a pointer to the first location after the message. The uncompressed name is placed in the buffer indicated by _e_x_p___d_n which is of size _l_e_n_g_t_h. The size of compressed name is returned or -1 if there was an error. The variables _s_t_a_t_p_-_>_r_e_s___h___e_r_r_n_o / ___r_e_s_._r_e_s___h___e_r_r_n_o and external variable _h___e_r_r_n_o is set whenever an error occurs during resolver operation. The following definitions are given in _<_n_e_t_d_b_._h_>: #define NETDB_INTERNAL -1 /* see errno */ #define NETDB_SUCCESS 0 /* no problem */ #define HOST_NOT_FOUND 1 /* Authoritative Answer Host not found */ #define TRY_AGAIN 2 /* Non-Authoritative not found, or SERVFAIL */ #define NO_RECOVERY 3 /* Non-Recoverable: FORMERR, REFUSED, NOTIMP */ #define NO_DATA 4 /* Valid name, no data for requested type */ The hheerrrroorr() function writes a message to the diagnostic output consist- ing of the string parameter _s, the constant string ": ", and a message corresponding to the value of _h___e_r_r_n_o. The hhssttrreerrrroorr() function returns a string which is the message text cor- responding to the value of the _e_r_r parameter. FFIILLEESS /etc/resolv.conf See resolver(5). SSEEEE AALLSSOO gethostbyname(3), hostname(7), resolver(5); RFC1032, RFC1033, RFC1034, RFC1035, RFC974; SMM:11, ``Name Server Operations Guide for BIND'' 4th Berkeley Distribution July 4, 2000 4th Berkeley Distribution