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 .TH GETIFADDRS 3 2012\-11\-11 GNU "Linux Programmer's Manual"
  42 .SH 名前
  43 getifaddrs, freeifaddrs \- インターフェースのアドレスを取得する
  44 .SH 書式
  45 .nf
  46 \fB#include <sys/types.h>\fP
  47 \fB#include <ifaddrs.h>\fP
  48 .sp
  49 \fBint getifaddrs(struct ifaddrs **\fP\fIifap\fP\fB);\fP
  50 .sp
  51 \fBvoid freeifaddrs(struct ifaddrs *\fP\fIifa\fP\fB);\fP
  52 .fi
  53 .SH 説明
  54 \fBgetifaddrs\fP() 関数は、ローカルシステムのネットワークインターフェース情報を表す構造体の連結リストを作成し、
  55 リストの先頭の要素のアドレスを \fI*ifap\fP に格納する。 リストは \fIifaddrs\fP 構造体で構成される。 \fIifaddrs\fP
  56 構造体は以下のように定義されている。
  57 .sp
  58 .in +4n
  59 .nf
  60 struct ifaddrs {
  61     struct ifaddrs  *ifa_next;    /* Next item in list */
  62     char            *ifa_name;    /* Name of interface */
  63     unsigned int     ifa_flags;   /* Flags from SIOCGIFFLAGS */
  64     struct sockaddr *ifa_addr;    /* Address of interface */
  65     struct sockaddr *ifa_netmask; /* Netmask of interface */
  66     union {
  67         struct sockaddr *ifu_broadaddr;
  68                          /* Broadcast address of interface */
  69         struct sockaddr *ifu_dstaddr;
  70                          /* Point\-to\-point destination address */
  71     } ifa_ifu;
  72 #define              ifa_broadaddr ifa_ifu.ifu_broadaddr
  73 #define              ifa_dstaddr   ifa_ifu.ifu_dstaddr
  74     void            *ifa_data;    /* Address\-specific data */
  75 };
  76 .fi
  77 .in
  78 .PP
  79 \fIifa_next\fP フィールドにはリストの次の構造体へのポインタが格納される。 この要素がリストの最後の場合には NULL が入る。
  80 .PP
  81 .\" The constant
  82 .\" .B IF NAMESIZE
  83 .\" indicates the maximum length of this field.
  84 \fIifa_name\fP は NULL 終端されたインターフェース名を指す。
  85 .PP
  86 \fIifa_flags\fP フィールドには、 \fBSIOCGIFFLAGS\fP \fBioctl\fP(2) 操作で返されるインターフェースのフラグが格納される
  87 (これらのフラグのリストについては \fBnetdevice\fP(7) を参照)。
  88 .PP
  89 \fIifa_addr\fP フィールドは、インターフェースのアドレスを格納した構造体へのポインタである (\fIsa_family\fP
  90 サブフィールドを参照して、アドレス構造体の形式を判別すべきである)。 このフィールドは NULL ポインタとなる場合がある。
  91 .PP
  92 \fIifa_netmask\fP フィールドには、 ネットマスクがあるアドレスファミリーであれば、 \fIifa_addr\fP
  93 に関連付けられたネットマスクを格納した構造体へのポインタが入る。 このフィールドは NULL ポインタとなる場合がある。
  94 .PP
  95 \fIifa_flags\fP にビット \fBIFF_BROADCAST\fP か \fBIFF_POINTOPOINT\fP のどちらが設定されているかにより
  96 (同時にはこれらのどちらか一方だけが設定される)、 \fIifa_broadaddr\fP に \fIifa_addr\fP に対応するブロードキャストが入るか
  97 (そのアドレスファミリーでブロードキャストがある場合)、 \fIifa_dstaddr\fP に point\-to\-point
  98 インターフェースの宛先アドレスが入るかが決まる。
  99 .PP
 100 \fIifa_data\fP フィールドは、 アドレスファミリー固有のデータが入ったバッファへのポインタである。
 101 そのインターフェースでこのようなデータがない場合には、 このフィールドは NULL となる。
 102 .PP
 103 \fBgetifaddrs\fP() が返すデータは動的に確保される。 必要なくなった際には \fBfreeifaddrs\fP() を使って解放すべきである。
 104 .SH 返り値
 105 成功すると、 \fBgetifaddrs\fP は 0 を返す。 エラーの場合、 \-1 が返り、 \fIerrno\fP が適切に設定される。
 106 .SH エラー
 107 \fBgetifaddrs\fP() は失敗する場合があり、その場合には \fIerrno\fP には \fBsocket\fP(2), \fBbind\fP(2),
 108 \fBgetsockname\fP(2), \fBrecvmsg\fP(2), \fBsendto\fP(2), \fBmalloc\fP(3), \fBrealloc\fP(3)
 109 に対して規定されているエラーのいずれかが設定される。
 110 .SH バージョン
 111 \fBgetifaddrs\fP() 関数は glibc 2.3 で初めて登場したが、 glibc 2.3.3 より前のバージョンの実装では IPv4
 112 アドレスだけがサポートされていた。 IPv6 のサポートは glibc 2.3.3 で追加された。 IPv4 以外のアドレスファミリーが
 113 \fBgetifaddrs\fP で利用できるのは、 netlink をサポートするカーネルの場合だけである。
 114 .SH 準拠
 115 .\" , but the BSD-derived documentation generally
 116 .\" appears to be confused and obsolete on this point.
 117 .\" i.e., commonly it still says one of them will be NULL, even if
 118 .\" the ifa_ifu union is already present
 119 POSIX.1\-2001 にはない。 この関数は BSDi で初めて登場し、 BSD 系のシステムに存在するが、
 120 ドキュメント上はかなり動作が異なり、アドレス毎ではなくインターフェース毎に 1 エントリを返す。 このことは、
 121 インターフェースがアドレスを持たない場合には \fIifa_addr\fP や他のフィールドは実際に NULL になり、 インターフェースに IP
 122 アドレスが割り当てられている場合には リンクレベルのアドレスは返されない、ということを意味する。 また、 \fIifa_broadaddr\fP と
 123 \fIifa_dstaddr\fP のどちらを選択するかを決める方法は、 システムにより異なる。
 124 .SH 注意
 125 Linux では、 返されるアドレスは通常インターフェースに割り当てられた IPv4 アドレスと IPv6 アドレスになるが、
 126 これ以外にインターフェース毎に一つ \fBAF_PACKET\fP アドレスも返される。 \fBAF_PACKET\fP アドレスには、
 127 インターフェースとその物理層に関する低レベルの詳細が格納される。 この場合、 \fIifa_data\fP フィールドには、
 128 \fI<linux/if_link.h>\fP で定義される \fIstruct rtnl_link_stats\fP (Linux 2.4
 129 以前では \fI<linux/netdevice.h>\fP で定義される \fIstruct net_device_stats\fP)
 130 へのポインタが格納される。 この構造体には、インターフェースの様々な属性や統計情報が入る。
 131 .SH 例
 132 以下のプログラムは \fBgetifaddrs\fP(), \fBfreeifaddrs\fP(), \fBgetnameinfo\fP(3) の使用例である。
 133 以下はこのプログラムをあるシステムで実行した際の出力である。
 134 .in +4n
 135 .nf
 136
 137 $ \fB./a.out\fP
 138 lo      address family: 17 (AF_PACKET)
 139 eth0    address family: 17 (AF_PACKET)
 140 lo      address family: 2 (AF_INET)
 141         address: <127.0.0.1>
 142 eth0    address family: 2 (AF_INET)
 143         address: <10.1.1.4>
 144 lo      address family: 10 (AF_INET6)
 145         address: <::1>
 146 eth0    address family: 10 (AF_INET6)
 147         address: <fe80::2d0:59ff:feda:eb51%eth0>
 148 .fi
 149 .in
 150 .SS プログラムのソース
 151 \&
 152 .nf
 153 #include <arpa/inet.h>
 154 #include <sys/socket.h>
 155 #include <netdb.h>
 156 #include <ifaddrs.h>
 157 #include <stdio.h>
 158 #include <stdlib.h>
 159 #include <unistd.h>
 160
 161 int
 162 main(int argc, char *argv[])
 163 {
 164     struct ifaddrs *ifaddr, *ifa;
 165     int family, s;
 166     char host[NI_MAXHOST];
 167
 168     if (getifaddrs(&ifaddr) == \-1) {
 169         perror("getifaddrs");
 170         exit(EXIT_FAILURE);
 171     }
 172
 173     /* Walk through linked list, maintaining head pointer so we
 174        can free list later */
 175
 176     for (ifa = ifaddr; ifa != NULL; ifa = ifa\->ifa_next) {
 177         if (ifa\->ifa_addr == NULL)
 178             continue;
 179
 180         family = ifa\->ifa_addr\->sa_family;
 181
 182         /* Display interface name and family (including symbolic
 183            form of the latter for the common families) */
 184
 185         printf("%s\t  address family: %d%s\en",
 186                 ifa\->ifa_name, family,
 187                 (family == AF_PACKET) ? " (AF_PACKET)" :
 188                 (family == AF_INET) ?   " (AF_INET)" :
 189                 (family == AF_INET6) ?  " (AF_INET6)" : "");
 190
 191         /* For an AF_INET* interface address, display the address */
 192
 193         if (family == AF_INET || family == AF_INET6) {
 194             s = getnameinfo(ifa\->ifa_addr,
 195                     (family == AF_INET) ? sizeof(struct sockaddr_in) :
 196                                           sizeof(struct sockaddr_in6),
 197                     host, NI_MAXHOST, NULL, 0, NI_NUMERICHOST);
 198             if (s != 0) {
 199                 printf("getnameinfo() failed: %s\en", gai_strerror(s));
 200                 exit(EXIT_FAILURE);
 201             }
 202             printf("\etaddress: <%s>\en", host);
 203         }
 204     }
 205
 206     freeifaddrs(ifaddr);
 207     exit(EXIT_SUCCESS);
 208 }
 209 .fi
 210 .SH 関連項目
 211 \fBbind\fP(2), \fBgetsockname\fP(2), \fBsocket\fP(2), \fBpacket\fP(7), \fBifconfig\fP(8)
 212 .SH この文書について
 213 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.53 の一部
 214 である。プロジェクトの説明とバグ報告に関する情報は
 215 http://www.kernel.org/doc/man\-pages/ に書かれている。