draft/man3/inet_pton.3

   1 .\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com>
   2 .\" and Copyright (c) 2008 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\"
  24 .\" References: RFC 2553
  25 .\"
  26 .\" Japanese Version Copyright (c) 2001 NAKANO Takeo all rights reserved.
  27 .\" Translated 2001-01-14, NAKANO Takeo <nakano@apm.seikei.ac.jp>
  28 .\" Updated 2008-08-08, Akihiro MOTOKI, LDP v3.05
  29 .\"
  30 .TH INET_PTON 3  2008-06-18 "Linux" "Linux Programmer's Manual"
  31 .\"O .SH NAME
  32 .\"O inet_pton \- convert IPv4 and IPv6 addresses from text to binary form
  33 .SH 名前
  34 inet_pton \- IPv4/IPv6 アドレスをテキスト形式からバイナリ形式に変換する
  35 .\"O .SH SYNOPSIS
  36 .SH 書式
  37 .nf
  38 .B #include <arpa/inet.h>
  39
  40 .BI "int inet_pton(int " "af" ", const char *" "src" ", void *" "dst" );
  41 .fi
  42 .\"O .SH DESCRIPTION
  43 .SH 説明
  44 .\"O This function converts the character string
  45 .\"O .I src
  46 .\"O into a network address structure in the
  47 .\"O .I af
  48 .\"O address family, then
  49 .\"O copies
  50 .\"O the network address structure to
  51 .\"O .IR dst .
  52 この関数は文字列
  53 .I src
  54 を、アドレスファミリー
  55 .I af
  56 のネットワークアドレス構造体に変換し、
  57 .I dst
  58 にコピーする。
  59 .\"O The
  60 .\"O .I af
  61 .\"O argument must be either
  62 .\"O .B AF_INET
  63 .\"O or
  64 .\"O .BR AF_INET6 .
  65 .I af
  66 引き数は
  67 .B AF_INET
  68 か
  69 .B AF_INET6
  70 のどちらかでなければならない。
  71 .PP
  72 .\"O The following address families are currently supported:
  73 現在サポートされているアドレスファミリーは以下の通りである。
  74 .TP
  75 .B AF_INET
  76 .\"O .I src
  77 .\"O points to a character string containing an IPv4 network address in
  78 .\"O dotted-decimal format, "\fIddd.ddd.ddd.ddd\fP", where
  79 .\"O .I ddd
  80 .\"O is a decimal number of up to three digits in the range 0 to 255.
  81 .\"O The address is converted to a
  82 .\"O .I struct in_addr
  83 .\"O and copied to
  84 .\"O .IR dst ,
  85 .\"O which must be
  86 .\"O .I sizeof(struct in_addr)
  87 .\"O (4) bytes (32 bits) long.
  88 .I src
  89 はドット区切りの 10 進数形式 "\fIddd.ddd.ddd.ddd\fP"
  90 の IPv4 ネットワークアドレス文字列へのポインタである。
  91 .I ddd
  92 は 0 から 255 までの範囲の最大 3 桁の 10 進数である。
  93 このアドレスは
  94 .I "struct in_addr"
  95 に変換されて
  96 .I dst
  97 にコピーされる。
  98 .I dst
  99 の長さは
 100 .I "sizeof(struct in_addr)"
 101 (4) バイト (32ビット) でなければならない。
 102 .TP
 103 .B AF_INET6
 104 .\"O .I src
 105 .\"O points to a character string containing an IPv6 network address.
 106 .\"O The address is converted to a
 107 .\"O .I struct in6_addr
 108 .\"O and copied to
 109 .\"O .IR dst ,
 110 .\"O which must be
 111 .\"O .I sizeof(struct in6_addr)
 112 .\"O (16) bytes (128 bits) long.
 113 .I src
 114 は IPv6 ネットワークアドレスが格納された文字列へのポインタである。
 115 このアドレスは
 116 .I "struct in6_addr"
 117 に変換されて
 118 .I dst
 119 にコピーされる。
 120 .I dst
 121 の長さは
 122 .I "sizeof(struct in6_addr)"
 123 (16) バイト (128 ビット) でなければならない。
 124 .\"O The allowed formats for IPv6 addresses follow these rules:
 125 以下の 3 つのルールにしたがった形式が IPv6 アドレスとして入力できる。
 126 .RS
 127 .IP 1. 3
 128 .\"O The preferred format is
 129 .\"O .IR x:x:x:x:x:x:x:x .
 130 .\"O This form consists of eight hexadecimal numbers,
 131 .\"O each of which expresses a 16-bit value (i.e., each
 132 .\"O .I x
 133 .\"O can be up to 4 hex digits).
 134 推奨形式は
 135 .I x:x:x:x:x:x:x:x
 136 である。この形式は 8 個の 16 進数から構成され、
 137 各々の 16 進数は 16 ビット値を表す
 138 .RI ( x
 139 は最大 4 桁の 16 進数である)。
 140 .IP 2.
 141 .\"O A series of contiguous zero values in the preferred format
 142 .\"O can be abbreviated to
 143 .\"O .IR :: .
 144 .\"O Only one instance of
 145 .\"O .I ::
 146 .\"O can occur in an address.
 147 .\"O For example, the loopback address
 148 .\"O .I 0:0:0:0:0:0:0:1
 149 .\"O can be abbreviated as
 150 .\"O .IR ::1 .
 151 .\"O The wildcard address, consisting of all zeros, can be written as
 152 .\"O .IR :: .
 153 推奨形式の中の連続する 0 の列は
 154 .I ::
 155 に短縮できる。アドレス中で使用できる
 156 .I ::
 157 は 1 個だけである。
 158 例えば、ループバックアドレス
 159 .I 0:0:0:0:0:0:0:1
 160 は
 161 .I ::1
 162 と短縮できる。
 163 全ビットが 0 で構成されるワイルドカードアドレスは
 164 .I ::
 165 と記載できる。
 166 .IP 3.
 167 .\"O An alternate format is useful for expressing IPv4-mapped IPv6 addresses.
 168 .\"O This form is written as
 169 .\"O .IR x:x:x:x:x:x:d.d.d.d ,
 170 .\"O where the six leading
 171 .\"O .IR x s
 172 .\"O are hexadecimal values that define the six most-significant
 173 .\"O 16-bit pieces of the address (i.e., 96 bits), and the
 174 .\"O .IR d s
 175 .\"O express a value in dotted-decimal notation that
 176 .\"O defines the least significant 32 bits of the address.
 177 .\"O An example of such an address is
 178 .\"O .IR ::FFFF:204.152.189.116 .
 179 IPv4 をマッピングした IPv6 アドレスを表記するには別の形式が便利である。
 180 この別の形式は
 181 .I x:x:x:x:x:x:d.d.d.d
 182 と書くことができる。
 183 最初の 6 個の
 184 .I x
 185 はアドレスを 16 ビット単位に区切ったときの上位側 6 個分 (つまり 96 ビット分)
 186 を定義する 16 進数であり、
 187 .I d
 188 の部分はアドレスの下位 32 ビットをドット区切りの 10 進数表記で表したものである。
 189 .I ::FFFF:204.152.189.116
 190 はこの形式の例である。
 191 .RE
 192 .IP
 193 .\"O See RFC 2373 for further details on the representation of IPv6 addresses.
 194 IPv6 アドレスの表現方法の詳細については RFC 2373 を参照のこと。
 195 .\"O .SH "RETURN VALUE"
 196 .SH 返り値
 197 .\"O .BR inet_pton ()
 198 .\"O returns 1 on success (network address was successfully converted).
 199 .\"O 0 is returned if
 200 .\"O .I src
 201 .\"O does not contain a character string representing a valid network
 202 .\"O address in the specified address family.
 203 .\"O If
 204 .\"O .I af
 205 .\"O does not contain a valid address family, \-1 is returned and
 206 .\"O .I errno
 207 .\"O is set to
 208 .\"O .BR EAFNOSUPPORT .
 209 成功する (ネットワークアドレスが正常に変換される) と、
 210 .BR inet_pton ()
 211 は 1 を返す。
 212 .I src
 213 が指定されたアドレスファミリーに対する
 214 正しいネットワークアドレス表記でない場合には、
 215 0 を返す。
 216 .I af
 217 がサポートされているアドレスファミリーでない場合には、
 218 \-1 を返し、
 219 .I errno
 220 に
 221 .B EAFNOSUPPORT
 222 を設定する。
 223 .\"O .SH "CONFORMING TO"
 224 .SH 準拠
 225 POSIX.1-2001.
 226 .\"O .SH NOTES
 227 .SH 注意
 228 .\"O Unlike
 229 .\"O .BR inet_aton (3)
 230 .\"O and
 231 .\"O .BR inet_addr (3),
 232 .\"O .BR inet_pton ()
 233 .\"O supports IPv6 addresses.
 234 .BR inet_aton (3)
 235 や
 236 .BR inet_addr (3)
 237 と異なり、
 238 .BR inet_pton ()
 239 は IPv6 アドレスに対応している。
 240 .\"O On the other hand,
 241 .\"O .BR inet_pton ()
 242 .\"O only accepts IPv4 addresses in dotted-decimal notation, whereas
 243 .\"O .BR inet_aton (3)
 244 .\"O and
 245 .\"O .BR inet_addr (3)
 246 .\"O allow the more general numbers-and-dots notation (hexadecimal
 247 .\"O and octal number formats, and formats that don't require all
 248 .\"O four bytes to be explicitly written).
 249 .\"O For an interface that handles both IPv6 addresses, and IPv4
 250 .\"O addresses in numbers-and-dots notation, see
 251 .\"O .BR getaddrinfo (3).
 252 一方で、
 253 .BR inet_pton ()
 254 が受け付ける IPv4 アドレスはドット区切りの 10 進数表記だけである。
 255 これに対し、
 256 .BR inet_aton (3)
 257 や
 258 .BR inet_addr (3)
 259 ではもっと一般的なドット区切りの数字表記 (16 進数や 8 進数の形式や、
 260 4 バイト全てを明示的に書かなくてもよい形式) が使用できる。
 261 ドット区切りの数字表記で IPv6 アドレスと IPv4 アドレスの両方を扱える
 262 インターフェイスについては、
 263 .BR getaddrinfo (3)
 264 を参照のこと。
 265 .\"O .SH BUGS
 266 .SH バグ
 267 .\"O .B AF_INET6
 268 .\"O does not recognize IPv4 addresses.
 269 .\"O An explicit IPv4-mapped IPv6 address must be supplied in
 270 .\"O .I src
 271 .\"O instead.
 272 .B AF_INET6
 273 は IPv4 アドレスを認識しない。
 274 代わりに IPv4 アドレスをマッピングした IPv6 アドレスを
 275 .I src
 276 に与えなければならない。
 277 .\"O .SH EXAMPLE
 278 .SH 例
 279 .\"O The program below demonstrates the use of
 280 .\"O .BR inet_pton ()
 281 .\"O and
 282 .\"O .BR inet_ntop (3).
 283 .\"O Here are some example runs:
 284 以下のプログラムは
 285 .BR inet_pton ()
 286 と
 287 .BR inet_ntop (3)
 288 の使用例を示すものである。
 289 実行すると以下のようになる。
 290 .in +4n
 291 .nf
 292
 293 .RB "$" " ./a.out i6 0:0:0:0:0:0:0:0"
 294 ::
 295 .RB "$" " ./a.out i6 1:0:0:0:0:0:0:8"
 296 1::8
 297 .RB "$" " ./a.out i6 0:0:0:0:0:FFFF:204.152.189.116"
 298 ::ffff:204.152.189.116
 299 .fi
 300 .in
 301 .\"O .SS Program source
 302 .SS プログラムのソース
 303 \&
 304 .nf
 305 #include <arpa/inet.h>
 306 #include <stdio.h>
 307 #include <stdlib.h>
 308 #include <string.h>
 309
 310 int
 311 main(int argc, char *argv[])
 312 {
 313     unsigned char buf[sizeof(struct in6_addr)];
 314     int domain, s;
 315     char str[INET6_ADDRSTRLEN];
 316
 317     if (argc != 3) {
 318         fprintf(stderr, "Usage: %s {i4|i6|<num>} string\\n", argv[0]);
 319         exit(EXIT_FAILURE);
 320     }
 321
 322     domain = (strcmp(argv[1], "i4") == 0) ? AF_INET :
 323              (strcmp(argv[1], "i6") == 0) ? AF_INET6 : atoi(argv[1]);
 324
 325     s = inet_pton(domain, argv[2], buf);
 326     if (s <= 0) {
 327         if (s == 0)
 328             fprintf(stderr, "Not in presentation format");
 329         else
 330             perror("inet_pton");
 331         exit(EXIT_FAILURE);
 332     }
 333
 334     if (inet_ntop(domain, buf, str, INET6_ADDRSTRLEN) == NULL) {
 335         perror("inet_ntop");
 336         exit(EXIT_FAILURE);
 337     }
 338
 339     printf("%s\\n", str);
 340
 341     exit(EXIT_SUCCESS);
 342 }
 343 .fi
 344 .\"O .SH "SEE ALSO"
 345 .SH 関連項目
 346 .BR getaddrinfo (3),
 347 .BR inet (3),
 348 .BR inet_ntop (3)