.\" 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
.\" %FreeBSD: src/lib/libc/net/resolver.3,v 1.11.2.7 2001/12/14 18:33:55 ru Exp %
.\" $FreeBSD$
.\"
.Dd June 4, 1993
.Dt RESOLVER 3
.Os
.Sh 名称
.Nm res_query ,
.Nm res_search ,
.Nm res_mkquery ,
.Nm res_send ,
.Nm res_init ,
.Nm dn_comp ,
.Nm dn_expand
.Nd リゾルバルーチン
.Sh ライブラリ
.Lb libc
.Sh 書式
.In sys/types.h
.In netinet/in.h
.In arpa/nameser.h
.In resolv.h
.Ft int
.Fo res_query
.Fa "const char *dname"
.Fa "int class"
.Fa "int type"
.Fa "u_char *answer"
.Fa "int anslen"
.Fc
.Ft int
.Fo res_search
.Fa "const char *dname"
.Fa "int class"
.Fa "int type"
.Fa "u_char *answer"
.Fa "int anslen"
.Fc
.Ft int
.Fo res_mkquery
.Fa "int op"
.Fa "const char *dname"
.Fa "int class"
.Fa "int type"
.Fa "const u_char *data"
.Fa "int datalen"
.Fa "const u_char *newrr_in"
.Fa "u_char *buf"
.Fa "int buflen"
.Fc
.Ft int
.Fo res_send
.Fa "const u_char *msg"
.Fa "int msglen"
.Fa "u_char *answer"
.Fa "int anslen"
.Fc
.Ft int
.Fn res_init
.Fo dn_comp
.Fa "const char *exp_dn"
.Fa "u_char *comp_dn"
.Fa "int length"
.Fa "u_char **dnptrs"
.Fa "u_char **lastdnptr"
.Fc
.Ft int
.Fo dn_expand
.Fa "const u_char *msg"
.Fa "const u_char *eomorig"
.Fa "const u_char *comp_dn"
.Fa "char *exp_dn"
.Fa "int length"
.Fc
.Sh 解説
これらのルーチンは、インターネットドメインネームサーバを使用し、
問い合わせと応答メッセージの作成、送信、解釈を行います。
.Pp
リゾルバルーチンが使用するグローバルな設定と状態の情報は、構造体
.Em _res
に保存されます。
ほとんどの値は、適切なデフォルト値になっているので無視できます。  
.Em _res.options
に保存されるオプションは、
.Pa resolv.h
で以下のように定義されています。
オプションは、有効なオプションのビット論理和をとった、
単純なビットマスクとして保存されています。 
.Bl -tag -width RES_USE_INET6
.It Dv RES_INIT
初期ネームサーバアドレスとデフォルトドメイン名が初期化されている場合は
真です (
.Fn res_init
が呼び出された場合など)。
.It Dv RES_DEBUG
デバッグメッセージを出力します。
.It Dv RES_AAONLY
信頼できる応答のみを受け入れます。
このオプションを使用した場合、信頼できる応答かエラーが見つかるまで 
.Fn res_send
を続ける必要があります。
現在のところ、これは実装されていません。
.It Dv RES_USEVC
UDP データグラムの代わりに
.Tn TCP
接続を問い合わせに使用します。
.It Dv RES_STAYOPEN
.Dv RES_USEVC
とともに使用し、問い合わせと問い合わせの間も
.Tn TCP
接続を開いたままに保ちます。
多くの問い合わせを定期的に行うプログラムのみで便利です。
通常の使用には
.Tn UDP
を使うべきです。
.It Dv RES_IGNTC
現在は使用されません (トランケーションエラーを無視します、すなわち、
.Tn TCP
で再試行しません)。
.It Dv RES_RECURSE
問い合わせの反復要求ビットを設定します。
これがデフォルトです (
.Fn res_send
は反復問い合わせを行なわず、ネームサーバが反復を処理することを期待します)。
.It Dv RES_DEFNAMES
設定すると、
.Fn res_search
がシングルコンポーネント名 (ドットを含まない名前) に
デフォルトのドメイン名を追加するようになります。
このオプションはデフォルトで有効になっています。
.It Dv RES_DNSRCH
このオプションを設定すると、
.Fn res_search
が、現在のドメインと親ドメインでホスト名を検索するようになります。
.Xr hostname 7
を参照してください。
これは、標準ホスト検索ルーチン
.Xr gethostbyname 3
によって使用されます。
このオプションはデフォルトで有効になっています。 
.It Dv NOALIASES
このオプションは、
.Dq Ev HOSTALIASES
環境変数によって制御されるユーザレベルのエイリアシング機能を無効にします。
ネットワークデーモンでは、このオプションを設定する必要があります。
.It Dv RES_USE_INET6
IPv6 のみのアプリケーションのサポートを有効にします。
IPv4 アドレスは IPv4 射影アドレスとして返されるようになります。
たとえば、
.Li 10.1.1.1
は
.Li ::ffff:10.1.1.1
のように返されます。
このオプションは、特定のカーネルコンフィギュレーションの場合にだけ意味が
あります。
.It Dv RES_USE_EDNS0
EDNS0 拡張の OPT pseudo-RR のサポートを有効にします。
このオプションにより、リゾルバコードは DNS 問い合わせに OPT pseudo-RR を
加えて、こちらの受け取りバッファの大きさを通知します。
このオプションにより、DNS サーバはデフォルトでない大きさの受け取りバッファを
利用できるので、より大きな応答を送ることができるようになります。
EDNS0 拡張されたDNS 問い合わせパケットは非 EDNS0 DNS サーバとは
互換性がありません。
.El
.Pp
.Fn res_init
ルーチンは、設定ファイルを読み込み (設定ファイルが存在する場合。
.Xr resolver 5
参照)、デフォルトドメイン名、検索リスト、ローカルネームサーバの
インターネットアドレスを入手します。
サーバが設定されていない場合は、リゾルバを実行しているホストが試されます。
現在のドメイン名は、設定ファイルで指定されていない場合、
ホスト名で定義されますが、環境変数
.Ev LOCALDOMAIN
で上書きすることもできます。
検索リストをプロセスごとに上書きする場合は、
ブランクで区切られた複数のトークンをこの環境変数に含めます。
これは、設定ファイルの 
.Em search
コマンドに似ています。
別の環境変数
.Dq Ev RES_OPTIONS
を設定すれば、特定の内部リゾルバオプションを上書きできます。
内部リゾルバオプションは、上書きされなければ、
.Em _res
構造体のフィールドを変更することで設定されるか、設定ファイルの
.Em options
コマンドから継承されます。
.Dq Ev RES_OPTIONS
環境変数のシンタックスについては、
.Xr resolver 5
を参照してください。
通常の場合、初期化は以下のルーチンを初めて呼び出したときに実行されます。
.Pp
.Fn res_query
関数は、サーバ問い合わせメカニズムのインタフェースを提供するもので、
問い合わせの作成、作成された問い合わせのローカルサーバへの送信、応答の待機、
応答の予備チェックを行います。
問い合わせは、完全な形でのドメイン名
.Fa dname
に対する、指定された
.Fa type
と
.Fa class
の情報を要求します。
応答メッセージは
.Fa answer
バッファに残され、呼び出し側が指定する
.Fa anslen
の長さになっています。
.Pp
.Fn res_search
ルーチンは、
.Fn res_query
と同じように問い合わせの作成と応答の待機を行いますが、それに加えて
.Dv RES_DEFNAMES
と
.Dv RES_DNSRCH
オプションによって制御されるデフォルトと検索規則も実装しています。
このルーチンは最初に成功した応答を返します。
.Pp
残りのルーチンは、
.Fn res_query
が使用する低レベルルーチンです。
.Fn res_mkquery
関数は、標準問い合わせメッセージを作成して
.Fa buf
に配置し、問い合わせのサイズを返します。
問い合わせが
.Fa buflen
より長い場合は -1 を返します。
問い合わせタイプ
.Fa op
は、通常の場合
.Dv QUERY
ですが、
.Aq Pa arpa/nameser.h
で定義されているどの問い合わせタイプにもできます。
問い合わせのドメイン名は
.Fa dname
で指定します。
.Fa newrr
は現在使用されていませんが、更新メッセージを作成するためのものです。
.Pp
.Fn res_send
ルーチンは、事前フォーマット済み問い合わせを送信し、応答を返します。
.Dv RES_INIT
が設定されていない場合は
.Fn res_init
を呼び出します。
ローカルネームサーバへの問い合わせの送信、およびタイムアウトと
再試行の処理も行います。
応答メッセージの長さを返しますが、エラーがあった場合は -1 を返します。
.Pp
.Fn dn_comp
関数は、ドメイン名
.Fa exp_dn
を圧縮し、
.Fa comp_dn
に保存します。
圧縮された名前のサイズを返しますが、エラーがあった場合は -1 を返します。 
.Fa comp_dn
が指す配列のサイズは
.Fa length
で指定します。
圧縮の際、現在のメッセージでそれまでに圧縮された名前を指すポインタ 
.Fa dnptrs
の配列を使用します。
最初のポインタはメッセージの最初を指し、リストは
.Dv NULL
で終わります。配列の制限は
.Fa lastdnptr
で指定します。
.Fn dn_comp
の副作用は、名前が圧縮されたときにメッセージに挿入されるラベルのポインタの
リストが更新されることです。 
.Em dnptr
が
.Dv NULL
である場合、名前は圧縮されません。
.Fa lastdnptr
が
.Dv NULL
である場合、ラベルのリストは更新されません。
.Pp
.Fn dn_expand
エントリは、圧縮されたドメイン名
.Fa comp_dn
を完全なドメイン名に展開します。
圧縮された名前は、問い合わせもしくは応答メッセージに含まれます。
.Fa msg
は、メッセージの最初を指すポインタです。
展開された名前は、
.Fa exp_dn
が示すサイズ
.Fa length
のバッファに配置されます。
圧縮された名前のサイズが返されますが、
エラーがあった場合は -1 が返されます。 
.Sh 関連ファイル
.Bl -tag -width /etc/resolv.conf
.It Pa /etc/resolv.conf
設定ファイル。
.Xr resolver 5
を参照のこと。
.El
.Sh 関連項目
.Xr gethostbyname 3 ,
.Xr resolver 5 ,
.Xr hostname 7 ,
.Xr named 8
.Pp
.%T RFC1032 ,
.%T RFC1033 ,
.%T RFC1034 ,
.%T RFC1035 ,
.%T RFC974
.Rs
.%T "Name Server Operations Guide for BIND"
.Re
.Sh 歴史
.Fn res_query
関数は
.Bx 4.3
で登場しました。