.\"
.\" 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 $
.\" %FreeBSD: src/lib/libc/net/addr2ascii.3,v 1.7.2.4 2001/08/17 15:42:38 ru Exp %
.\"
.\" $FreeBSD$
.Dd June 13, 1996
.Dt ADDR2ASCII 3
.Os
.Sh 名称
.Nm addr2ascii ,
.Nm ascii2addr
.Nd 一般的なアドレスフォーマットルーチン
.Sh ライブラリ
.Lb libc
.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
(in
.Aq Pa netinet/in.h )
.It Dv AF_LINK
.Li struct sockaddr_dl
(in
.Aq Pa net/if_dl.h )
.\" .It Dv AF_INET6
.\" .Li struct in6_addr
.\" (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 Er
.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
に渡された文字列は、
アドレスファミリ
.Fa af
について不適切にフォーマットされていました。
.El
.Sh 関連項目
.Xr inet 3 ,
.Xr linkaddr 3 ,
.Xr inet 4
.Sh 歴史
これに近いインタフェースは、もともと Craig Partridge によって
提案されました。
このインタフェース自体は、
.Tn INRIA
の
.Tn IPv6
の実装により、はじめて登場しました。
.Sh 作者
コードとドキュメントは MIT Laboratory for Computer Science の
.An Garrett A. Wollman
によるものです。
.Sh バグ
オリジナルの実装は IPv6 をサポートしていました。
このサポートは、そのうち復活されるはずです。
.Tn NRL
の実装には、
.Dv AF_ISO
および
.Dv AF_NS
アドレスファミリのサポートも含まれていました。
.Pp
このインタフェースの一般性については、いくらか疑問があります。
本当に一般的なインタフェースであれば、バッファを動的に割り当てることが
できるよう、使用されるバッファの長さを決定する手段を備えているでしょうし、
バイナリアドレスを保持するのには必ず
.Dq Li struct sockaddr
を要求するでしょう。
残念ながら、これは既存のやり方と互換性がありません。
この制限のため、任意のアドレスファミリからネットワークアドレスを
印字するルーチンは、必要な最大バッファ長や、
バイナリアドレスとして使用するアドレスの適切な部分といった
内部的な知識を依然として持っていなければなりません。