.\"
.\" Copyright 1996 Massachusetts Institute of Technology
.\"
.\" Permission to use, copy, modify, and distribute this software and
.\" its documentation for any purpose and without fee is hereby
.\" granted, provided that both the above copyright notice and this
.\" permission notice appear in all copies, that both the above
.\" copyright notice and this permission notice appear in all
.\" supporting documentation, and that the name of M.I.T. not be used
.\" in advertising or publicity pertaining to distribution of the
.\" software without specific, written prior permission.  M.I.T. makes
.\" no representations about the suitability of this software for any
.\" purpose.  It is provided "as is" without express or implied
.\" warranty.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
.\" SHALL M.I.T. 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.
.\"
.\"	$ANA: addr2ascii.3,v 1.1 1996/06/13 18:41:46 wollman Exp $
.\"
.Dd June 13, 1996
.Dt ADDR2ASCII 3
.Os
.Sh 名称
.Nm addr2ascii ,
.Nm ascii2addr
.Nd 一般的なアドレスフォーマット化ルーチン
.Sh 書式
.Fd #include <sys/types.h>
.Fd #include <netinet/in.h>
.Fd #include <arpa/inet.h>
.Ft "char *"
.Fn addr2ascii "int af" "const void *addrp" "int len" "char *buf"
.Ft int
.Fn ascii2addr "int af" "const char *ascii" "void *result"
.Sh 解説
ルーチン
.Fn addr2ascii
と
.Fn ascii2addr
は、バイナリ形式と、アドレスファミリに
適切な印刷可能形式の間でネットワークアドレスを変換するのに使用されます。
両方の関数が、変換プロセスで使用されるアドレスファミリを指定する
.Fa af
引数を
使用します (現時点では、
.Dv AF_INET
および
.Dv AF_LINK
アドレスファミリだけがサポートされています)。
.Pp
.Fn addr2ascii
関数は、バイナリのネットワーク形式のアドレス印刷可能な形式に
変換するのに使用されます。
.Fa af
に加えて、
3 つの他の引数があります。
.Fa addrp
引数は、変換するネットワークアドレスを指すポインタです。
.Fa len
引数は、
アドレスの長さです。
.Fa buf
引数は、結果を保持するために呼び出し元が割り振る
バッファを指すオプションのポインタです。
ヌルポインタが渡されると、
.Fn addr2ascii
は静的に割り振られたバッファを使用します。
.Pp
.Fn ascii2addr
関数は、
.Fn addr2ascii
と逆の演算を実行します。
.Fa af
に加えて、
2 つのパラメータ
.Fa ascii
と
.Fa result
を使用します。
.Fa ascii
パラメータは、バイナリに
変換されるストリングを指すポインタです。
.Fa result
パラメータは、指定のファミリ
に適切なネットワークアドレス構造を指すポインタです。
.Pp
指定ファイル内のバイナリアドレスを使用するのに適切な構造は次のとおりです。
.Pp
.Bl -tag -width AF_INETxxxx -compact
.It Dv AF_INET
.Li struct in_addr
.Pq in Aq Pa netinet/in.h
.It Av AF_LINK
.Li struct sockaddr_dl
.Pq in Aq Pa net/if_dl.h
.\" .It Dv AF_INET6
.\" .Li struct in6_addr
.\" .Pq in Aq Pa netinet6/in6.h
.El
.Sh 戻り値
.Fn addr2ascii
関数は、渡されたバッファのアドレス、または
NULL
ポインタが
渡された場合は静的バッファのアドレスを返します。処理が失敗した場合は、
ヌルポインタを返します。
.Fn ascii2addr
関数は、バイナリアドレスの長さ (バイト単位)
を返します。処理が失敗した場合は
-1 を返します。
.Pp
.Sh 例
.Xr inet 3
関数
.Fn inet_ntoa
と
.Fn inet_aton
は次のように実現できます。
.Bd -literal -offset indent
#include <sys/types.h>
#include <sys/socket.h>
#Include <netinet/in.h>
#include <arpa/inet.h>

char *
inet_ntoa(struct in_addr addr)
{
	return addr2ascii(AF_INET, &addr, sizeof addr, 0);
}

int
inet_aton(const char *ascii, struct in_addr *addr)
{
	return (ascii2addr(AF_INET, ascii, addr)
	    == sizeof(*addr));
}
.Ed
.Pp
実際には、これは実行できません。
.Fn addr2ascii
と
.Fn ascii2addr
は、他の方法でなく、
.Xr inet 3
関数で実現されているからです。
.Sh エラー
処理失敗が返されたとき、
.Li errno
に次の値の 1 つの設定されます。
.Bl -tag -width [EPROTONOSUPPORT]
.It Bq Er ENAMETOOLONG
.Fn addr2ascii
ルーチンは、
.Fa af
によって渡されたアドレスファミリに不適切なパラメータ
.Fa len
を渡されました。
.It Bq Er EPROTONOSUPPORT
いずれかのルーチンに、
.Dv AF_INET
または
.Dv AF_LINK
ではない
.Fa af 
パラメータが渡されました。
.It Bq er EINVAL
.Fn ascii2addr
によって渡された
.Fn ascii2addr
に渡された文字列は、
アドレスファミリ
.Fa af
について不適切にフォーマットされていました。
.El
.Sh 関連項目
.Xr inet 3 ,
.Xr linkaddr 3 ,
.Xr inet 4
.Sh 歴史
これに近いインタフェースは、オリジナルには Craig Partridge
が提案しました。
このインタフェース自体は、
.Tn INRIA
.Tn IPv6
インプリメントに最初に現れたものです。
.Sh 作者
コードとドキュメンテーションは
.An Garrett A. Wollman ,
MIT Laboratory for Computer Science
によるものです。
.Sh バグ
オリジナルの実装は IPv6 をサポートしていました。このサポートは、
しだいに復活されるはずです。
.Tn NRL
の実装は、
.Dv AF_ISO
および
.Dv AF_NS
のアドレスファミリのサポートを組み込んでいるはずです。
.Pp
このインタフェースの一般性については、いくらか疑問があります。真に一般的な
インタフェースは、使用されるバッファの長さを決定する手段を備えています。
動的に割り当てでき、バイナリアドレスとして保存するのに必ず
.Dq Li struct sockaddr
を使用とするからです。不都合なことに、これは
既存のやり方と互換性がありません。この制限は、任意のアドレスファミリからの
ネットワークアドレスを印刷するルーチンには、必要な最大バッファ長と、
バイナリアドレスとして使用するアドレスの該当する部分の内部的な
知識がなければならないことを意味します。
.\" kuma