diff options
Diffstat (limited to 'lib/libc/net/resolver.3')
| -rw-r--r-- | lib/libc/net/resolver.3 | 344 |
1 files changed, 344 insertions, 0 deletions
diff --git a/lib/libc/net/resolver.3 b/lib/libc/net/resolver.3 new file mode 100644 index 00000000000..99abe17f036 --- /dev/null +++ b/lib/libc/net/resolver.3 @@ -0,0 +1,344 @@ +.\" $NetBSD: resolver.3,v 1.5 1995/02/25 06:21:02 cgd Exp $ +.\" +.\" Copyright (c) 1985, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)resolver.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt RESOLVER 3 +.Os BSD 4.3 +.Sh NAME +.Nm res_query , +.Nm res_search , +.Nm res_mkquery , +.Nm res_send , +.Nm res_init , +.Nm dn_comp , +.Nm dn_expand +.Nd resolver routines +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <netinet/in.h> +.Fd #include <arpa/nameser.h> +.Fd #include <resolv.h> +.Fo res_query +.Fa "char *dname" +.Fa "int class" +.Fa "int type" +.Fa "u_char *answer" +.Fa "int anslen" +.Fc +.Fo res_search +.Fa "char *dname" +.Fa "int class" +.Fa "int type" +.Fa "u_char *answer" +.Fa "int anslen" +.Fc +.Fo res_mkquery +.Fa "int op" +.Fa "char *dname" +.Fa "int class" +.Fa "int type" +.Fa "char *data" +.Fa "int datalen" +.Fa "struct rrec *newrr" +.Fa "char *buf" +.Fa "int buflen" +.Fc +.Fo res_send +.Fa "char *msg" +.Fa "int msglen" +.Fa "char *answer" +.Fa "int anslen" +.Fc +.Fn res_init +.Fo dn_comp +.Fa "char *exp_dn" +.Fa "char *comp_dn" +.Fa "int length" +.Fa "char **dnptrs" +.Fa "char **lastdnptr" +.Fc +.Fo dn_expand +.Fa "u_char *msg" +.Fa "u_char *eomorig" +.Fa "u_char *comp_dn" +.Fa "u_char *exp_dn" +.Fa "int length" +.Fc +.Sh DESCRIPTION +These routines are used for making, sending and interpreting +query and reply messages with Internet domain name servers. +.Pp +Global configuration and state information that is used by the +resolver routines is kept in the structure +.Em _res . +Most of the values have reasonable defaults and can be ignored. +Options +stored in +.Em _res.options +are defined in +.Pa resolv.h +and are as follows. +Options are stored as a simple bit mask containing the bitwise ``or'' +of the options enabled. +.Bl -tag -width RES_DEFNAMES +.It Dv RES_INIT +True if the initial name server address and default domain name are +initialized (i.e., +.Fn res_init +has been called). +.It Dv RES_DEBUG +Print debugging messages. +.It Dv RES_AAONLY +Accept authoritative answers only. +With this option, +.Fn res_send +should continue until it finds an authoritative answer or finds an error. +Currently this is not implemented. +.It Dv RES_USEVC +Use +.Tn TCP +connections for queries instead of +.Tn UDP +datagrams. +.It Dv RES_STAYOPEN +Used with +.Dv RES_USEVC +to keep the +.Tn TCP +connection open between +queries. +This is useful only in programs that regularly do many queries. +.Tn UDP +should be the normal mode used. +.It Dv RES_IGNTC +Unused currently (ignore truncation errors, i.e., don't retry with +.Tn TCP ) . +.It Dv RES_RECURSE +Set the recursion-desired bit in queries. +This is the default. +.Pf ( Fn res_send +does not do iterative queries and expects the name server +to handle recursion.) +.It Dv RES_DEFNAMES +If set, +.Fn res_search +will append the default domain name to single-component names +(those that do not contain a dot). +This option is enabled by default. +.It Dv RES_DNSRCH +If this option is set, +.Fn res_search +will search for host names in the current domain and in parent domains; see +.Xr hostname 7 . +This is used by the standard host lookup routine +.Xr gethostbyname 3 . +This option is enabled by default. +.El +.Pp +The +.Fn res_init +routine +reads the configuration file (if any; see +.Xr resolv.conf 5 ) +to get the default domain name, +search list and +the 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 hostname +if not specified in the configuration file; +it can be overridden by the environment variable +.Ev LOCALDOMAIN . +This environment variable may contain several blank-separated +tokens if you wish to override the +.Fa search list +on a per-process basis. +This is similar to the +.Fa search +command in the configuration file. +Another environment variable +.Ev RES_OPTIONS +can be set to override certain internal resolver options which +are otherwise set by changing fields in the +.Fa _res +structure or are inherited from the configuration file's +.Fa options +command. +The syntax of the +.Ev RES_OPTIONS +environment variable is explained in +.Xr resolv.conf 5 . +Initialization normally occurs on the first call +to one of the following routines. +.Pp +The +.Fn res_query +function 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 specified +.Fa type +and +.Fa class +for the specified fully-qualified domain name +.Fa dname . +The reply message is left in the +.Fa answer +buffer with length +.Fa anslen +supplied by the caller. +.Pp +The +.Fn res_search +routine makes a query and awaits a response like +.Fn res_query , +but in addition, it implements the default and search rules +controlled by the +.Dv RES_DEFNAMES +and +.Dv RES_DNSRCH +options. +It returns the first successful reply. +.Pp +The remaining routines are lower-level routines used by +.Fn res_query . +The +.Fn res_mkquery +function +constructs a standard query message and places it in +.Fa buf . +It returns the size of the query, or \-1 if the query is +larger than +.Fa buflen . +The query type +.Fa op +is usually +.Dv QUERY , +but can be any of the query types defined in +.Aq Pa arpa/nameser.h . +The domain name for the query is given by +.Fa dname . +.Fa Newrr +is currently unused but is intended for making update messages. +.Pp +The +.Fn res_send +routine +sends a pre-formatted query and returns an answer. +It will call +.Fn res_init +if +.Dv RES_INIT +is not set, send the query to the local name server, and +handle timeouts and retries. +The length of the reply message is returned, or +\-1 if there were errors. +.Pp +The +.Fn dn_comp +function +compresses the domain name +.Fa exp_dn +and stores it in +.Fa comp_dn . +The size of the compressed name is returned or \-1 if there were errors. +The size of the array pointed to by +.Fa comp_dn +is given by +.Fa length . +The compression uses +an array of pointers +.Fa dnptrs +to previously-compressed names in the current message. +The first pointer points to +to the beginning of the message and the list ends with +.Dv NULL . +The limit to the array is specified by +.Fa lastdnptr . +A side effect of +.Fn dn_comp +is to update the list of pointers for +labels inserted into the message +as the name is compressed. +If +.Em dnptr +is +.Dv NULL, names are not compressed. +If +.Fa lastdnptr +is +.Dv NULL , +the list of labels is not updated. +.Pp +The +.Fn dn_expand +entry +expands the compressed domain name +.Fa comp_dn +to a full domain name +The compressed name is contained in a query or reply message; +.Fa msg +is a pointer to the beginning of the message. +The uncompressed name is placed in the buffer indicated by +.Fa exp_dn +which is of size +.Fa length . +The size of compressed name is returned or \-1 if there was an error. +.Sh FILES +.Bl -tag -width Pa +/etc/resolv.conf +The configuration file +see +.Xr resolv.conf 5 . +.El +.Sh SEE ALSO +.Xr gethostbyname 3 , +.Xr named 8 , +.Xr resolv.conf 5 , +.Xr hostname 7 , +.Pp +.%T RFC1032 , +.%T RFC1033 , +.%T RFC1034 , +.%T RFC1035 , +.%T RFC974 +.Rs +.%T "Name Server Operations Guide for BIND" +.Re +.Sh HISTORY +The +.Nm +function appeared in +.Bx 4.3 . |