301 lines
8.8 KiB
Groff
301 lines
8.8 KiB
Groff
|
.\" Copyright (c) 1985, 1995 The Regents of the University of California.
|
||
|
|
.\" All rights reserved.
|
||
|
|
.\"
|
||
|
|
.\" Redistribution and use in source and binary forms are permitted provided
|
||
|
|
.\" that: (1) source distributions retain this entire copyright notice and
|
||
|
|
.\" comment, and (2) distributions including binaries display the following
|
||
|
|
.\" acknowledgement: ``This product includes software developed by the
|
||
|
|
.\" University of California, Berkeley and its contributors'' in the
|
||
|
|
.\" documentation or other materials provided with the distribution and in
|
||
|
|
.\" all advertising materials mentioning features or use of this software.
|
||
|
|
.\" 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 ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
|
||
|
|
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
||
|
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
||
|
|
.\"
|
||
|
|
.\" @(#)resolver.3 6.5 (Berkeley) 6/23/90
|
||
|
|
.\" $Id: resolver.3,v 8.5 1997/03/14 02:29:48 vixie Exp $
|
||
|
|
.\"
|
||
|
|
.Dd December 11, 1995
|
||
|
|
.Dt RESOLVER @LIB_NETWORK_EXT_U@
|
||
|
|
.Os BSD 4
|
||
|
|
.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>
|
||
|
|
.Fn res_query "const char *dname" "int class, type" "u_char *answer" "int anslen"
|
||
|
|
.Fn res_search "const char *dname" "int class, type" "u_char *answer" "int anslen"
|
||
|
|
.Fn res_mkquery "int op" "const char *dname" "int class, type" "const char *data" "int datalen" "struct rrec *newrr" "u_char *buf" "int buflen"
|
||
|
|
.Fn res_send "const u_char *msg" "int msglen" "u_char *answer" "int anslen"
|
||
|
|
.Fn res_init
|
||
|
|
.Fn dn_comp "const char *exp_dn" "u_char *comp_dn" "int length" "u_char **dnptrs, **lastdnptr"
|
||
|
|
.Fn dn_expand "const u_char *msg, *eomorig, *comp_dn" "char *exp_dn" "int length"
|
||
|
|
.Fn herror "const char *s"
|
||
|
|
.Fn hstrerror "int err"
|
||
|
|
.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
|
||
|
|
.Ft _res .
|
||
|
|
Most of the values have reasonable defaults and can be ignored.
|
||
|
|
Options
|
||
|
|
stored in
|
||
|
|
.Ft _res.options
|
||
|
|
are defined in
|
||
|
|
.Pa resolv.h
|
||
|
|
and are as follows.
|
||
|
|
Options are stored as a simple bit mask containing the bitwise
|
||
|
|
.Dq OR
|
||
|
|
of the options enabled.
|
||
|
|
.Bl -tag -width "RES_DEB"
|
||
|
|
.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 TCP connections for queries instead of UDP datagrams.
|
||
|
|
.It Dv RES_STAYOPEN
|
||
|
|
Used with
|
||
|
|
.Dv 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.
|
||
|
|
.It Dv RES_IGNTC
|
||
|
|
Unused currently (ignore truncation errors, i.e., don't retry with TCP).
|
||
|
|
.It Dv RES_RECURSE
|
||
|
|
Set the recursion-desired bit in queries.
|
||
|
|
This is the default.
|
||
|
|
(\c
|
||
|
|
.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 @DESC_EXT@ .
|
||
|
|
This is used by the standard host lookup routine
|
||
|
|
.Xr gethostbyname @LIB_NETWORK_EXT@ .
|
||
|
|
This option is enabled by default.
|
||
|
|
.It Dv RES_NOALIASES
|
||
|
|
This option turns off the user level aliasing feature controlled by
|
||
|
|
the
|
||
|
|
.Ev HOSTALIASES
|
||
|
|
environment variable. Network daemons should set this option.
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn res_init
|
||
|
|
routine
|
||
|
|
reads the configuration file (if any; see
|
||
|
|
.Xr resolver @FORMAT_EXT@ )
|
||
|
|
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
|
||
|
|
.Dq search list
|
||
|
|
on a per-process basis. This is similar to the
|
||
|
|
.Ic search
|
||
|
|
command in the configuration file.
|
||
|
|
Another environment variable
|
||
|
|
.Pq Dq Ev RES_OPTIONS
|
||
|
|
can be set to override certain internal resolver options which are otherwise
|
||
|
|
set by changing fields in the
|
||
|
|
.Ft _res
|
||
|
|
structure or are inherited from the configuration file's
|
||
|
|
.Ic options
|
||
|
|
command. The syntax of the
|
||
|
|
.Dq Ev RES_OPTIONS
|
||
|
|
environment variable is explained in
|
||
|
|
.Xr resolver @FORMAT_EXT@ .
|
||
|
|
Initialization normally occurs on the first call
|
||
|
|
to one of the other resolver 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
|
||
|
|
.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
|
||
|
|
.Fa 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.
|
||
|
|
.Pp
|
||
|
|
The external variable
|
||
|
|
.Ft h_errno
|
||
|
|
is set whenever an error occurs during resolver operation. The following
|
||
|
|
definitions are given in
|
||
|
|
.Pa <netdb.h> :
|
||
|
|
.Bd -literal
|
||
|
|
#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 */
|
||
|
|
.Ed
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn herror
|
||
|
|
function writes a message to the diagnostic output consisting of the string
|
||
|
|
parameter
|
||
|
|
.Fa s ,
|
||
|
|
the constant string ": ", and a message corresponding to the value of
|
||
|
|
.Ft h_errno .
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn hstrerror
|
||
|
|
function returns a string which is the message text corresponding to the
|
||
|
|
value of the
|
||
|
|
.Fa err
|
||
|
|
parameter.
|
||
|
|
.Sh FILES
|
||
|
|
.Bl -tag -width "/etc/resolv.conf "
|
||
|
|
.It Pa /etc/resolv.conf
|
||
|
|
See
|
||
|
|
.Xr resolver @FORMAT_EXT@ .
|
||
|
|
.El
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr gethostbyname @LIB_NETWORK_EXT@ ,
|
||
|
|
.Xr hostname @DESC_EXT@ ,
|
||
|
|
.Xr @INDOT@named @SYS_OPS_EXT@ ,
|
||
|
|
.Xr resolver @FORMAT_EXT@ ;
|
||
|
|
RFC1032, RFC1033, RFC1034, RFC1035, RFC974;
|
||
|
|
SMM:11,
|
||
|
|
.Dq Name Server Operations Guide for Sy BIND
|