MAN page from RedHat Other bind-chroot-devel-8.1.2-9.i386.rpm

RESOLVER

Section: C Library Functions (3)
Index
BSD mandoc
BSD 4

NAME

res_query res_search res_mkquery res_send res_init dn_comp dn_expand - resolver routines

SYNOPSIS

Fd #include <sys/types.h>Fd #include <netinet/in.h>Fd #include <arpa/nameser.h>Fd #include <resolv.h>Fn res_query const char *dname int class, type u_char *answer int anslenFn res_search const char *dname int class, type u_char *answer int anslenFn res_mkquery int op const char *dname int class, type const char *data int datalen struct rrec *newrr u_char *buf int buflenFn res_send const u_char *msg int msglen u_char *answer int anslenFn res_initFn dn_comp const char *exp_dn u_char *comp_dn int length u_char **dnptrs, **lastdnptrFn dn_expand const u_char *msg, *eomorig, *comp_dn char *exp_dn int lengthFn herror const char *sFn hstrerror int err

DESCRIPTION

These routines are used for making, sending and interpretingquery and reply messages with Internet domain name servers.

Global configuration and state information that is used by theresolver routines is kept in the structureFt _res .Most of the values have reasonable defaults and can be ignored.Optionsstored inFt _res.optionsare defined inresolv.hand 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 areinitialized (i.e.,Fn res_inithas been called).
RES_DEBUG: Print debugging messages.
RES_AAONLY: Accept authoritative answers only.With this option,Fn res_sendshould 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: Unused currently (ignore truncation errors, i.e., don't retry with TCP).
RES_RECURSE: Set the recursion-desired bit in queries.This is the default.(Fn res_senddoes not do iterative queries and expects the name serverto handle recursion.)
RES_DEFNAMES: If set,Fn res_searchwill 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,Fn res_searchwill search for host names in the current domain and in parent domains; seehostname(7).This is used by the standard host lookup routinegethostbyname(3).This option is enabled by default.
RES_NOALIASES: This option turns off the user level aliasing feature controlled bythe HOSTALIASES environment variable. Network daemons should set this option.

TheFn res_initroutinereads the configuration file (if any; seeresolver(5))to get the default domain name, search list andthe Internet address of the local name server(s).If no server is configured, the host running the resolver is tried.The current domain name is defined by the hostnameif not specified in the configuration file;it can be overridden by the environment variable LOCALDOMAIN This environment variable may contain several blank-separatedtokens if you wish to override the``search list''on a per-process basis. This is similar to thesearchcommand in the configuration file.Another environment variable (``RES_OPTIONS '')can be set to override certain internal resolver options which are otherwiseset by changing fields in theFt _resstructure or are inherited from the configuration file'soptionscommand. The syntax of the ``RES_OPTIONS ''environment variable is explained inresolver(5).Initialization normally occurs on the first callto one of the other resolver routines.

TheFn res_queryfunction provides an interface to the server query mechanism.It 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 specifiedFa typeandFa classfor the specified fully-qualified domain nameFa dname .The reply message is left in theFa answerbuffer with lengthFa anslensupplied by the caller.

TheFn res_searchroutine makes a query and awaits a response likeFn res_query ,but in addition, it implements the default and search rulescontrolled by the RES_DEFNAMES and RES_DNSRCH options.It returns the first successful reply.

The remaining routines are lower-level routines used byFn res_query .TheFn res_mkqueryfunctionconstructs a standard query message and places it inFa buf .It returns the size of the query, or -1 if the query islarger thanFa buflen .The query typeFa opis usually QUERY , but can be any of the query types defined in<arpa/nameser.h> The domain name for the query is given byFa dname .Fa Newrris currently unused but is intended for making update messages.

TheFn res_sendroutinesends a pre-formatted query and returns an answer.It will callFn res_initif RES_INIT is not set, send the query to the local name server, andhandle timeouts and retries.The length of the reply message is returned, or -1 if there were errors.

TheFn dn_compfunctioncompresses the domain nameFa exp_dnand stores it inFa comp_dn .The size of the compressed name is returned or -1 if there were errors.The size of the array pointed to byFa comp_dnis given byFa length .The compression usesan array of pointersFa dnptrsto previously-compressed names in the current message.The first pointer points toto the beginning of the message and the list ends with NULL The limit to the array is specified byFa lastdnptr .A side effect ofFn dn_compis to update the list of pointers for labels inserted into the messageas the name is compressed. IfFa dnptris NULL , names are not compressed. IfFa lastdnptris NULL , the list of labels is not updated.

TheFn dn_expandentryexpands the compressed domain nameFa comp_dnto a full domain name.The compressed name is contained in a query or reply message;Fa msgis a pointer to the beginning of the message.The uncompressed name is placed in the buffer indicated byFa exp_dnwhich is of sizeFa length .The size of compressed name is returned or -1 if there was an error.

The external variableFt h_errnois set whenever an error occurs during resolver operation. The followingdefinitions are given in<netdb.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-Authoritive not found, or SERVFAIL */#define NO_RECOVERY    3   /* Nonrecoverable: FORMERR, REFUSED, NOTIMP */#define NO_DATA        4   /* Valid name, no data for requested type */

TheFn herrorfunction writes a message to the diagnostic output consisting of the stringparameterFa s ,the constant string ": ", and a message corresponding to the value ofFt h_errno .

TheFn hstrerrorfunction returns a string which is the message text corresponding to thevalue of theFa errparameter.

FILES

/etc/resolv.conf: See
resolver(5).

This document was created byman2html,using the manual pages.