resolver(3N)

NAME | SYNOPSIS | DESCRIPTION | FILES | ATTRIBUTES | SEE ALSO | NOTES

NAME

resolver, res_init, res_mkquery, res_mkupdate, res_mkupdrec, res_query, res_search, res_send, res_update, dn_comp, dn_expand- resolver routines

SYNOPSIS

cc [ flag ... ] file ... -lresolv  -lsocket  -lnsl [ library ... ]
#include <sys/types.h>
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>

int res_init(void);
int res_mkquery(int op, const char *dname, int class, int type, const char *data, int datalen, struct rrec *newrr, uchar_t *buf, int buflen);
int res_mkupdate(ns_updrec **rrecp_in, uchar *buf, int length);
ns_updrec *res_mkupdrec(int section, const char *dname, uint_t class, uint_t type, uint_t ttl);
int res_query(const char *dname, int class, int type, uchar_t *answer, int anslen);
int res_search(const char *dname, int class, int type, uchar_t *answer, int anslen);
int res_send(uchar_t *msg, int msglen, uchar_t *answer, int anslen);
int res_update(ns_updrec *rrecp_in);
int dn_comp(const char *exp_dn, uchar_t *comp_dn, int length, uchar_t **dnptrs, uchar_t **lastdnptr);
int dn_expand(const uchar_t *msg, const uchar_t *eomorig, uchar_t *comp_dn, char exp_dn, int length);

DESCRIPTION

These routines are used for making, sending, and interpreting query and reply messages passed to and from Internet domain name servers. The res_update() and res_mkupdrec() routines are used to dynamically update the name server with resource records.

The global structure _res holds options and state information. Option values can be set to affect the collective behavior of groups of resolver library routines. However, most resolver library routines use reasonable defaults so that the explicit enabling of an option is rarely required.

The library manual page entry for the resolver library includes public domain routines beyond those described here. See libresolv(4). Those function names that are exported but are not explained here are lower-level routines called by these routines. Their direct use is discouraged. If you do make direct use of unsupported routines, you do so at considerable added risk and with no expectation of documentation or other support beyond that available publicly.

Options for the resolver library are stored as a single bit mask containing the bitwise- OR sum of the options enabled. The options stored in _res.options are those defined in <resolv.h> and as follows. The field _res.options is a member of the _res structure.

RES_INIT

True if the initial name server address and default domain name are initialized, that is, res_init() has been called.

RES_DEBUG

Print debugging messages.

RES_AAONLY

Accept authoritative answers only. With this option, res_send() will continue until it finds an authoritative answer or finds an error. Currently this option is not implemented.

RES_USEVC

Use TCP connections for queries instead of UDP datagrams.

RES_PRIMARY

Query primary server only. This option is not implemented.

RES_IGNTC

Unused currently. Ignore truncation errors; that is, do not retry with TCP.

RES_RECURSE

Set the recursion-desired bit in queries. This is the default. res_send() does not do iterative queries and expects the name server to handle recursion.

RES_DEFNAMES

If set, res_search() appends the default domain name to single-component names (names that do not contain a dot). This is useful only in programs that regularly do many queries. UDP should be the normal mode used.

RES_DNSRCH

Enables searching up through the current domain tree. If this option is set, res_search() searches for host names in the current domain and in parent domains. This is used by the standard host lookup routine gethostbyname(3N). 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_init

If the system initialization file resolv.conf exists, res_init() reads it to get the default domain name, the search list, and the Internet address of the local name server or servers. See resolv.conf(4). If no server is configured by the local resolv.conf file, res_init tries to obtain name resolution services from the host on which it is running.

The res_init() function also sets the RES_INIT field of the _res global structure so that other service routines (res_search()) can determine for certain whether it needs to be called first before other processing begins.

In the absence of a resolv.conf configuration file, the current domain is either set to the value of the environmental variable LOCALDOMAIN, derived from the domain name or derived from the host name. See domainname(1M). The current domain name as defined in the system initialization file resolv.conf can be overridden by the environment variable LOCALDOMAIN. This environment 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 search command in the configuration file. Another environment variable ( RES_OPTIONS) can be set to override certain internal resolver options. Otherwise, these options are set by changing fields in the global _res structure or they are inherited from the configuration file's options command. The syntax of the RES_OPTIONS environment variable is explained in resolv.conf(4).

The initializations performed by res_init() can be invoked explicitly with this function. However, they are normally performed automatically as a result of a call to one of the other resolver routines.

res_search

res_search() formulates and sends a normal query (QUERY) message, and stores the response in a buffer supplied by the caller.

The parameters class and type define the class and type of query. See <arpa/nameser.h>. The response is returned in the user-supplied buffer answer. res_search returns the length of answer in anslen. Like the other resolver routines, res_search() calls res_init() if the RES_INIT flag is not enabled.

The res_search() function acts in a similar manner as res_query(), except that it can implement the default and search rules controlled by the RES_DEFNAMES and RES_DNSRCH options.

The parameter dname is the domain name. However, if dname consists of a single-component name and the RES_DEFNAMES flag is enabled (the default), dname is appended with the current domain name.

If the RES_DNSRCH flag is enabled, res_search() searches up the current domain tree until an answer has been retrieved or an unrecoverable error has been encountered. res_search() returns the first successful reply.

res_mkquery

The res_mkquery() function constructs a standard query message and places it in buf.

res_mkquery() returns the size of the query or -1 if the query is larger than buflen. The op parameter is usually QUERY, but can be any of the query types defined in <arpa/nameser.h>.

The parameter dname is the domain name for the query.

The parameters class and type define the class and type of query (see <arpa/nameser.h>). The parameter data is the resource record; datalen is the length of the record.

newrr is unused and should be specified as a null pointer (0).

res_query

The res_query function provides an interface to most of 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 specified type and class for the specified fully-qualified domain name dname. The reply message is left in the answer buffer with length anslen supplied by the caller. The res_mkquery and res_send routines described elsewhere in this section are lower-level routines that res_query calls.

res_send

res_send() sends a pre-formatted query to name servers and returns an answer. It calls res_init() if RES_INIT is not set, send the query to the local name server, and handle timeouts and retries. msg is the query sent; msglen is its length. answer is the response returned. The length of the response is stored in anslen. res_send() returns the length of the response or -1 if there were errors.

dn_expand

dn_expand() expands the compressed domain name given by the pointer comp_dn into a full domain name. Expanded names are converted to upper case. The compressed name is contained in a query or reply message; msg is a pointer to the beginning of that message. Expanded names are stored in the buffer referenced by the exp_dn buffer of size length, which should be large enough to hold the expanded result.

dn_expand() returns the size of the compressed name, or -1 if there was an error.

dn_comp

dn_comp() compresses the domain name exp_dn and stores it in comp_dn. dn_comp() returns the size of the compressed name, or -1 if there were errors. length is the size of the array pointed to by comp_dn. dnptrs is a pointer to the head of the list of pointers to previously compressed names in the current message. The first pointer must point to the beginning of the message. The list ends with NULL. The limit to the array is specified by lastdnptr.

A side effect of calling dn_comp() is to update the list of pointers for labels inserted into the message by dn_comp() as the name is compressed. However, if lastdnptr is NULL, dn_comp() does not update the list of labels. If dnptrs is NULL, names are not compressed.

res_mkupdrec

res_mkupdrec() takes the elements of a resource record as its arguments, for instance, section, domainname, class, type, and ttl, and returns a pointer to a linked list ns_updrec. It returns NULL upon failure.

res_update

res_update() takes a linked list of resource records ns_updrec as its only argument and separates the records into groups such that all records in a group will belong to a single name server. It creates a dynamic update packet for each zone and sends it to the name server and awaits an answer. Upon success, res_update() returns the number of zones updated. It returns <0 upon error.

res_mkupdate

res_mkupdate() creates update packets by running through the elements of the ns_updrec link list. It is called by res_update() to create packets for res_send() to send to the name server. res_mkupdate() returns the actual size of the packet, or

-1

Error in reading a word or number in the rdata portion for update packets.

-2

The length of the packet passed is insufficient.

-3

The zone section is not the first section in the linked list, or the section order has a problem.

-4

A number overflow.

-5

Unknown operations or no records.

If an error occurs it could leave the zones being updated in an inconsistent state. For example, a record might be successfully added to the forward lookup zone but the corresponding PTR record might have failed to update in the reverse lookup tables.

FILES

/etc/resolv.conf

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	Unsafe

SEE ALSO

domainname(1M), in.named(1M), nstest(1M), gethostbyname(3N), libresolv(4), resolv.conf(4), attributes(5)

Lottor, M., Domain Administrators Operators Guide, RFC 1033, SRI International, Menlo Park, Calif., November 1987.

Mockapetris, Paul, Domain Names - Concepts and Facilities, RFC 1034, Network Information Center, SRI International, Menlo Park, Calif., November 1987.

Mockapetris, Paul, Domain Names - Implementation and Specification, RFC 1035, Network Information Center, SRI International, Menlo Park, Calif., November 1987.

Partridge, Craig, Mail Routing and the Domain System, RFC 974, Network Information Center, SRI International, Menlo Park, Calif., January 1986. Stahl, M., Domain Administrators Guide, RFC 1032, SRI International, Menlo Park, Calif., November 1987.

Vixie, Paul;Dunlap, Keven J., Karels, Michael J., Name Server Operations Guide for BIND (public domain), Internet Software Consortium, 1996.

NOTES

These interfaces are unsafe in multithreaded applications. Unsafe interfaces should be called only from the main thread.

SunOS 5.7  Last Revised 23 Feb 1998

NAME | SYNOPSIS | DESCRIPTION | FILES | ATTRIBUTES | SEE ALSO | NOTES