.\" 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 .\" %FreeBSD: src/lib/libc/net/gethostbyname.3,v 1.12.2.7 2001/12/14 18:33:55 ru Exp % .\" $FreeBSD$ .\" .Dd May 25, 1995 .Dt GETHOSTBYNAME 3 .Os .Sh 名称 .Nm gethostbyname , .Nm gethostbyname2 , .Nm gethostbyaddr , .Nm gethostent , .Nm sethostent , .Nm endhostent , .Nm herror , .Nm hstrerror .Nd ネットワークホストのエントリの取得 .Sh ライブラリ .Lb libc .Sh 書式 .In netdb.h .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 Va h_name ホストの正式名。 .It Va h_aliases ホストの別名 (エイリアス) のヌルで終わる配列。 .It Va h_addrtype 返されるアドレスのタイプであり、通常は .Dv AF_INET 。 .It Va h_length アドレスのバイト数による長さ。 .It Va h_addr_list ホストのネットワークアドレスのヌルで終わる配列。 ホストアドレスはネットワークバイトオーダで返されます。 .It Va h_addr .Va h_addr_list にある最初のアドレスであり、後方互換用。 .El .Pp ネームサーバを使用する場合、名前がドットで終わっていない時は .Fn gethostbyname および .Fn gethostbyname2 は名前が付いたホストを、現在のドメインと親のドメインから検索します。 名前にドットが含まれてなく、且つ環境変数 .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 のそれぞれ呼び出し後にも、接続を保持するようにオプションを設定します。 フラグが 0 の時、問い合わせは .Tn UDP データグラムを使用して 実行されます。 .Pp .Fn endhostent 関数は .Tn TCP 接続をクローズします。 .Pp .Fn herror 関数は診断出力にメッセージを書き出します。 診断出力は文字列パラメータ .Fa s と、定数文字列 .Qq Li ":\ " と、 .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 のエラー状態は、 .Dv NULL ポインタが返ることで示されます。その場合は外部整数 .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 getaddrinfo 3 , .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 関数はファイルをクローズします。 .Sh 歴史 .Fn herror 関数は .Bx 4.3 で登場しました。 .Fn endhostent , .Fn gethostbyaddr , .Fn gethostbyname , .Fn gethostent , .Fn sethostent 関数は .Bx 4.2 で登場しました。 .Fn gethostbyname2 関数は .Tn BIND バージョン 4.9.4 ではじめて登場しました。 .Sh バグ これらの関数は静的データ記憶域を使用します。 後でこのデータを使う必要がある場合は、以後のこれらの関数呼び出しで データが上書きされる前に、コピーして保存する必要があります。 なお、アドレスデータとして受け入れるのは現在、 インターネットアドレスフォーマットだけです。