.\" Copyright (c) 1983, 1987, 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. .\" .\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 .\" %Id: gethostbyname.3,v 1.10 1998/06/06 05:50:44 jkoshy Exp % .\" .Dd May 25, 1995 .Dt GETHOSTBYNAME 3 .Os BSD 4.2 .Sh 名称 .Nm gethostbyname , .Nm gethostbyname2 , .Nm gethostbyaddr , .Nm gethostent , .Nm sethostent , .Nm endhostent , .Nm herror , .Nm hstrerror .Nd ネットワークホストのエントリの取得 .Sh 書式 .Fd #include .Vt extern int h_errno; .Ft struct hostent * .Fn gethostbyname "const char *name" .Ft struct hostent * .Fn gethostbyname2 "const char *name" "int af" .Ft struct hostent * .Fn gethostbyaddr "const char *addr" "int len" "int type" .Ft struct hostent * .Fn gethostent void .Ft void .Fn sethostent "int stayopen" .Ft void .Fn endhostent void .Ft void .Fn herror "const char *string" .Ft const char * .Fn hstrerror "int err" .Sh 解説 .Fn gethostbyname , .Fn gethostbyname2 , .Fn gethostbyaddr 関数はそれぞれ、 次に示す構造体を持つオブジェクトのポインタを返します。構造体には、 名前またはアドレスによって参照されるインターネットホストが記述されていて、 ネームサーバ .Xr named 8 から、または .Pa /etc/hosts にある行の内訳フィールドから 得られた情報を含んでいます。ローカルのネームサーバが実行されていない場合、 これらのルーチンは .Pa /etc/hosts を検索します。 .Bd -literal struct hostent { char *h_name; /* ホストの正式名 */ char **h_aliases; /* 別名リスト */ int h_addrtype; /* ホストアドレスタイプ */ int h_length; /* アドレスの長さ */ char **h_addr_list; /* ネームサーバからのアドレスリスト */ }; #define h_addr h_addr_list[0] /* アドレス、下位互換用 */ .Ed .Pp この構造体のメンバは次のとおりです。 .Bl -tag -width h_addr_list .It Fa h_name ホストの正式名。 .It Fa h_aliases ホストの別名 (エイリアス) のヌルで終わる配列。 .It Fa h_addrtype 返されるアドレスのタイプであり、通常は .Dv AF_INET 。 .It Fa h_length アドレスのバイト数による長さ。 .It Fa h_addr_list ホストのネットワークアドレスのヌルで終わる配列。 ホストアドレスはネットワークバイト順で返されます。 .It Fa h_addr .Fa h_addr_list にある最初のアドレスであり、下位互換用。 .El .Pp ネームサーバを使用する場合、 .Fn gethostbyname および .Fn gethostbyname は、目的の名前が付いたホストを、現在のドメインと親のドメインから検索します。 ただしこれは、名前がドットで終わっていない場合です。 名前にドットが含まれないか、または環境変数 .Dq Ev HOSTALIASES にエイリアスファイルの名前が含まれている場合は、 入力名に適合するエイリアスが最初にエイリアスファイルで検索されます。 ドメイン検索手続きとエイリアスファイル書式については、 .Xr hostname 7 を参照してください。 .Pp .Fn gethostbyname2 関数は .Fn gethostbyname の発展型で、 .Dv AF_INET 以外のアドレスファミリ、たとえば .Dv AF_INET6 での検索を可能にするためのものです。ただし現在は、 .Fa af 引数に .Dv AF_INET を指定する必要があります。他の値を指定すると .Fn gethostbyname2 関数は、 .Va h_errno を .Dv NETDB_INTERNAL に設定した後で、 .Dv NULL を返します。 .Pp .Fn sethostent 関数は、問い合わせ用に、接続した .Tn TCP ソケットの使用を要求する場合に使用できます。 .Fa stayopen フラグが 0 でなければ、 .Tn TCP によってすべての問い合わせをネームサーバに送り、 .Fn gethostbyname , .Fn gethostbyname2 , .Fn gethostbyaddr のそれぞれ呼び出し後にも、接続を保持するようにオプションが設定できます。 その他の場合、問い合わせは .Tn UDP データグラムを使用して 実行されます。 .Pp .Fn endhostent 関数は .Tn TCP 接続をクローズします。 .Pp .Fn herror 関数は診断出力にメッセージを書き出します。 診断出力は文字列パラメータ .Fa s と、定数文字列 ": " と、 .Va h_errno の値に対応するメッセージで構成されます。 .Pp .Fn hstrerror 関数は、 .Fa err パラメータの値に対応するメッセージテキストの 文字列を返します。 .Sh 関連ファイル .Bl -tag -width /etc/resolv.conf -compact .It Pa /etc/hosts .It Pa /etc/host.conf .It Pa /etc/resolv.conf .El .Sh 診断 .Fn gethostbyname , .Fn gethostbyname2 , .Fn gethostbyaddr のエラー状態は、ヌルポインタが返ることで示されます。その場合は外部整数 .Va h_errno をチェックすることにより、 一時的なエラーであるのか、 無効または未知のホスト名を指定したためかを判断できます。 .Fn herror ルーチンによって、エラーを記述するエラーメッセージを表示できます。 引数 .Fa string は、 .Dv NULL でなければ表示され、後にコロンとスペースが続きます。 エラーメッセージが終端の改行とともに印刷されます。 .Pp 変数 .Va h_errno は次の値を取り得ます。 .Bl -tag -width HOST_NOT_FOUND .It Dv HOST_NOT_FOUND 指定した名前のホストが未知です。 .It Dv TRY_AGAIN これは通常は一時的なエラーで、ローカルサーバが公式サーバ から応答が得られなかったことを意味します。しばらくして再度試みると成功する 場合があります。 .It Dv NO_RECOVERY なんらかの予期しないサーバエラーが発生しました。 これは回復不能なエラーです。 .It Dv NO_DATA 要求された名前は有効ですが、IP アドレスがありません。 これは一時的なエラーではありません。 指定したホスト名がネームサーバには知られているにもかかわらず、 対応するアドレスがないという意味です。 このネームサーバに対して同じドメイン名で別なタイプの要求を行うと、 回答が得られるかもしれません。 たとえばメールフォワーダがそのドメインに登録されている場合があります。 .El .Sh 関連項目 .Xr resolver 3 , .Xr hosts 5 , .Xr hostname 7 , .Xr named 8 .Sh 警告 ネームサーバは検索せずに .Pa /etc/hosts だけを検索するルーチンを使用するように .Xr libc 3 が構築された場合、 .Fn gethostent 関数が定義され、 .Fn sethostent および .Fn endhostent が再定義されます。 .Pp .Fn gethostent 関数は、 .Pa /etc/hosts ファイルの次の行を読み込みます。 この際、必要ならばファイルをオープンします。 .Pp .Fn sethostent 関数はファイル .Pa etc/hosts をオープンおよび/またはリワインドします。 .Fa stayopen 引数が 0 でなければ、 .Fn gethostbyname , .Fn gethostbyname2 , .Fn gethostbyaddr のそれぞれの呼び出しの後、ファイルはクローズされません。 .Pp .Fn endhostent 関数はファイルをクローズします。 .Pp .Sh 歴史 .Fn herror 関数は .Bx 4.3 で最初に取り入れられました。 .Fn endhostent , .Fn gethostbyaddr , .Fn gethostbyname , .Fn gethostent , .Fn sethostent 関数は .Bx 4.2 で最初に取り入れられました。 .Fn gethostbyname2 関数は bind-4.9.4 で最初に取り入れられました。 .Sh バグ これらの関数は静的データ記憶域を使用します。後でデータが必要な場合は、 以後の呼び出しで上書きする前にコピーして保存する必要があります。なお、 アドレスデータとして受け入れるのは現在、インターネットアドレスフォーマット だけです。