release/man3/getifaddrs.3

   1 .\" Copyright (c) 2008 Petr Baudis <pasky@suse.cz>
   2 .\" and copyright (c) 2009, Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" Redistribution and use in source and binary forms, with or without
  28 .\" modification, are permitted provided that the following conditions
  29 .\" are met:
  30 .\"
  31 .\" 2008-12-08 Petr Baudis <pasky@suse.cz>
  32 .\"    Rewrite the BSD manpage in the Linux man pages style and account
  33 .\"    for glibc specificities, provide an example.
  34 .\" 2009-01-14 mtk, many edits and changes, rewrote example program.
  35 .\"
  36 .\"*******************************************************************
  37 .\"
  38 .\" This file was generated with po4a. Translate the source file.
  39 .\"
  40 .\"*******************************************************************
  41 .\"
  42 .\" Japanese Version Copyright (c) 2013  Akihiro MOTOKI
  43 .\"         all rights reserved.
  44 .\" Translated 2013-07-31, Akihiro MOTOKI <amotoki@gmail.com>
  45 .\"
  46 .TH GETIFADDRS 3 2014\-02\-26 GNU "Linux Programmer's Manual"
  47 .SH 名前
  48 getifaddrs, freeifaddrs \- インターフェースのアドレスを取得する
  49 .SH 書式
  50 .nf
  51 \fB#include <sys/types.h>\fP
  52 \fB#include <ifaddrs.h>\fP
  53 .sp
  54 \fBint getifaddrs(struct ifaddrs **\fP\fIifap\fP\fB);\fP
  55 .sp
  56 \fBvoid freeifaddrs(struct ifaddrs *\fP\fIifa\fP\fB);\fP
  57 .fi
  58 .SH 説明
  59 \fBgetifaddrs\fP() 関数は、ローカルシステムのネットワークインターフェース情報を表す構造体の連結リストを作成し、
  60 リストの先頭の要素のアドレスを \fI*ifap\fP に格納する。 リストは \fIifaddrs\fP 構造体で構成される。 \fIifaddrs\fP
  61 構造体は以下のように定義されている。
  62 .sp
  63 .in +4n
  64 .nf
  65 struct ifaddrs {
  66     struct ifaddrs  *ifa_next;    /* Next item in list */
  67     char            *ifa_name;    /* Name of interface */
  68     unsigned int     ifa_flags;   /* Flags from SIOCGIFFLAGS */
  69     struct sockaddr *ifa_addr;    /* Address of interface */
  70     struct sockaddr *ifa_netmask; /* Netmask of interface */
  71     union {
  72         struct sockaddr *ifu_broadaddr;
  73                          /* Broadcast address of interface */
  74         struct sockaddr *ifu_dstaddr;
  75                          /* Point\-to\-point destination address */
  76     } ifa_ifu;
  77 #define              ifa_broadaddr ifa_ifu.ifu_broadaddr
  78 #define              ifa_dstaddr   ifa_ifu.ifu_dstaddr
  79     void            *ifa_data;    /* Address\-specific data */
  80 };
  81 .fi
  82 .in
  83 .PP
  84 \fIifa_next\fP フィールドにはリストの次の構造体へのポインタが格納される。 この要素がリストの最後の場合には NULL が入る。
  85 .PP
  86 .\" The constant
  87 .\" .B IF NAMESIZE
  88 .\" indicates the maximum length of this field.
  89 \fIifa_name\fP はヌル終端されたインターフェース名を指す。
  90 .PP
  91 \fIifa_flags\fP フィールドには、 \fBSIOCGIFFLAGS\fP \fBioctl\fP(2) 操作で返されるインターフェースのフラグが格納される
  92 (これらのフラグのリストについては \fBnetdevice\fP(7) を参照)。
  93 .PP
  94 \fIifa_addr\fP フィールドは、インターフェースのアドレスを格納した構造体へのポインタである (\fIsa_family\fP
  95 サブフィールドを参照して、アドレス構造体の形式を判別すべきである)。 このフィールドはヌルポインタとなる場合がある。
  96 .PP
  97 \fIifa_netmask\fP フィールドには、 ネットマスクがあるアドレスファミリーであれば、 \fIifa_addr\fP
  98 に関連付けられたネットマスクを格納した構造体へのポインタが入る。 このフィールドはヌルポインタとなる場合がある。
  99 .PP
 100 \fIifa_flags\fP にビット \fBIFF_BROADCAST\fP か \fBIFF_POINTOPOINT\fP のどちらが設定されているかにより
 101 (同時にはこれらのどちらか一方だけが設定される)、 \fIifa_broadaddr\fP に \fIifa_addr\fP に対応するブロードキャストが入るか
 102 (そのアドレスファミリーでブロードキャストがある場合)、 \fIifa_dstaddr\fP に point\-to\-point
 103 インターフェースの宛先アドレスが入るかが決まる。
 104 .PP
 105 \fIifa_data\fP フィールドは、 アドレスファミリー固有のデータが入ったバッファへのポインタである。
 106 そのインターフェースでこのようなデータがない場合には、 このフィールドは NULL となる。
 107 .PP
 108 \fBgetifaddrs\fP() が返すデータは動的に確保される。 必要なくなった際には \fBfreeifaddrs\fP() を使って解放すべきである。
 109 .SH 返り値
 110 成功すると、 \fBgetifaddrs\fP は 0 を返す。 エラーの場合、 \-1 が返り、 \fIerrno\fP が適切に設定される。
 111 .SH エラー
 112 \fBgetifaddrs\fP() は失敗する場合があり、その場合には \fIerrno\fP には \fBsocket\fP(2), \fBbind\fP(2),
 113 \fBgetsockname\fP(2), \fBrecvmsg\fP(2), \fBsendto\fP(2), \fBmalloc\fP(3), \fBrealloc\fP(3)
 114 に対して規定されているエラーのいずれかが設定される。
 115 .SH バージョン
 116 \fBgetifaddrs\fP() 関数は glibc 2.3 で初めて登場したが、 glibc 2.3.3 より前のバージョンの実装では IPv4
 117 アドレスだけがサポートされていた。 IPv6 のサポートは glibc 2.3.3 で追加された。 IPv4 以外のアドレスファミリーが
 118 \fBgetifaddrs\fP で利用できるのは、 netlink をサポートするカーネルの場合だけである。
 119 .SH 準拠
 120 .\" , but the BSD-derived documentation generally
 121 .\" appears to be confused and obsolete on this point.
 122 .\" i.e., commonly it still says one of them will be NULL, even if
 123 .\" the ifa_ifu union is already present
 124 POSIX.1\-2001 にはない。 この関数は BSDi で初めて登場し、 BSD 系のシステムに存在するが、
 125 ドキュメント上はかなり動作が異なり、アドレス毎ではなくインターフェース毎に 1 エントリを返す。 このことは、
 126 インターフェースがアドレスを持たない場合には \fIifa_addr\fP や他のフィールドは実際に NULL になり、 インターフェースに IP
 127 アドレスが割り当てられている場合には リンクレベルのアドレスは返されない、ということを意味する。 また、 \fIifa_broadaddr\fP と
 128 \fIifa_dstaddr\fP のどちらを選択するかを決める方法は、 システムにより異なる。
 129 .SH 注意
 130 Linux では、 返されるアドレスは通常インターフェースに割り当てられた IPv4 アドレスと IPv6 アドレスになるが、
 131 これ以外にインターフェース毎に一つ \fBAF_PACKET\fP アドレスも返される。 \fBAF_PACKET\fP アドレスには、
 132 インターフェースとその物理層に関する低レベルの詳細が格納される。 この場合、 \fIifa_data\fP フィールドには、
 133 \fI<linux/if_link.h>\fP で定義される \fIstruct rtnl_link_stats\fP (Linux 2.4
 134 以前では \fI<linux/netdevice.h>\fP で定義される \fIstruct net_device_stats\fP)
 135 へのポインタが格納される。 この構造体には、インターフェースの様々な属性や統計情報が入る。
 136 .SH 例
 137 以下のプログラムは \fBgetifaddrs\fP(), \fBfreeifaddrs\fP(), \fBgetnameinfo\fP(3) の使用例である。
 138 以下はこのプログラムをあるシステムで実行した際の出力である。
 139 .in +4n
 140 .nf
 141
 142 $ \fB./a.out\fP
 143 lo       AF_PACKET (17)
 144                 tx_packets =        524; rx_packets =        524
 145                 tx_bytes   =      38788; rx_bytes   =      38788
 146 wlp3s0   AF_PACKET (17)
 147                 tx_packets =     108391; rx_packets =     130245
 148                 tx_bytes   =   30420659; rx_bytes   =   94230014
 149 em1      AF_PACKET (17)
 150                 tx_packets =          0; rx_packets =          0
 151                 tx_bytes   =          0; rx_bytes   =          0
 152 lo       AF_INET (2)
 153                 address: <127.0.0.1>
 154 wlp3s0   AF_INET (2)
 155                 address: <192.168.235.137>
 156 lo       AF_INET6 (10)
 157                 address: <::1>
 158 wlp3s0   AF_INET6 (10)
 159                 address: <fe80::7ee9:d3ff:fef5:1a91%wlp3s0>
 160 .fi
 161 .in
 162 .SS プログラムのソース
 163 \&
 164 .nf
 165 #define _GNU_SOURCE     /* To get defns of NI_MAXSERV and NI_MAXHOST */
 166 #include <arpa/inet.h>
 167 #include <sys/socket.h>
 168 #include <netdb.h>
 169 #include <ifaddrs.h>
 170 #include <stdio.h>
 171 #include <stdlib.h>
 172 #include <unistd.h>
 173 #include <linux/if_link.h>
 174
 175 int main(int argc, char *argv[])
 176 {
 177     struct ifaddrs *ifaddr, *ifa;
 178     int family, s, n;
 179     char host[NI_MAXHOST];
 180
 181     if (getifaddrs(&ifaddr) == \-1) {
 182         perror("getifaddrs");
 183         exit(EXIT_FAILURE);
 184     }
 185
 186     /* Walk through linked list, maintaining head pointer so we
 187        can free list later */
 188
 189     for (ifa = ifaddr, n = 0; ifa != NULL; ifa = ifa\->ifa_next, n++) {
 190         if (ifa\->ifa_addr == NULL)
 191             continue;
 192
 193         family = ifa\->ifa_addr\->sa_family;
 194
 195         /* Display interface name and family (including symbolic
 196            form of the latter for the common families) */
 197
 198         printf("%\-8s %s (%d)\en",
 199                ifa\->ifa_name,
 200                (family == AF_PACKET) ? "AF_PACKET" :
 201                (family == AF_INET) ? "AF_INET" :
 202                (family == AF_INET6) ? "AF_INET6" : "???",
 203                family);
 204
 205         /* For an AF_INET* interface address, display the address */
 206
 207         if (family == AF_INET || family == AF_INET6) {
 208             s = getnameinfo(ifa\->ifa_addr,
 209                     (family == AF_INET) ? sizeof(struct sockaddr_in) :
 210                                           sizeof(struct sockaddr_in6),
 211                     host, NI_MAXHOST,
 212                     NULL, 0, NI_NUMERICHOST);
 213             if (s != 0) {
 214                 printf("getnameinfo() failed: %s\en", gai_strerror(s));
 215                 exit(EXIT_FAILURE);
 216             }
 217
 218             printf("\et\etaddress: <%s>\en", host);
 219
 220         } else if (family == AF_PACKET && ifa\->ifa_data != NULL) {
 221             struct rtnl_link_stats *stats = ifa\->ifa_data;
 222
 223             printf("\et\ettx_packets = %10u; rx_packets = %10u\en"
 224                    "\et\ettx_bytes   = %10u; rx_bytes   = %10u\en",
 225                    stats\->tx_packets, stats\->rx_packets,
 226                    stats\->tx_bytes, stats\->rx_bytes);
 227         }
 228     }
 229
 230     freeifaddrs(ifaddr);
 231     exit(EXIT_SUCCESS);
 232 }
 233 .fi
 234 .SH 関連項目
 235 \fBbind\fP(2), \fBgetsockname\fP(2), \fBsocket\fP(2), \fBpacket\fP(7), \fBifconfig\fP(8)
 236 .SH この文書について
 237 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.67 の一部
 238 である。プロジェクトの説明とバグ報告に関する情報は
 239 http://www.kernel.org/doc/man\-pages/ に書かれている。