draft/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 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" Redistribution and use in source and binary forms, with or without
  25 .\" modification, are permitted provided that the following conditions
  26 .\" are met:
  27 .\"
  28 .\" 2008-12-08 Petr Baudis <pasky@suse.cz>
  29 .\"    Rewrite the BSD manpage in the Linux man pages style and account
  30 .\"    for glibc specificities, provide an example.
  31 .\" 2009-01-14 mtk, many edits and changes, rewrote example program.
  32 .\"
  33 .\"*******************************************************************
  34 .\"
  35 .\" This file was generated with po4a. Translate the source file.
  36 .\"
  37 .\"*******************************************************************
  38 .TH GETIFADDRS 3 2010\-10\-06 GNU "Linux Programmer's Manual"
  39 .SH 名前
  40 getifaddrs, freeifaddrs \- get interface addresses
  41 .SH 書式
  42 .nf
  43 \fB#include <sys/types.h>\fP
  44 \fB#include <ifaddrs.h>\fP
  45 .sp
  46 \fBint getifaddrs(struct ifaddrs **\fP\fIifap\fP\fB);\fP
  47 .sp
  48 \fBvoid freeifaddrs(struct ifaddrs *\fP\fIifa\fP\fB);\fP
  49 .fi
  50 .SH 説明
  51 The \fBgetifaddrs\fP()  function creates a linked list of structures describing
  52 the network interfaces of the local system, and stores the address of the
  53 first item of the list in \fI*ifap\fP.  The list consists of \fIifaddrs\fP
  54 structures, defined as follows:
  55 .sp
  56 .in +4n
  57 .nf
  58 struct ifaddrs {
  59     struct ifaddrs  *ifa_next;    /* Next item in list */
  60     char            *ifa_name;    /* Name of interface */
  61     unsigned int     ifa_flags;   /* Flags from SIOCGIFFLAGS */
  62     struct sockaddr *ifa_addr;    /* Address of interface */
  63     struct sockaddr *ifa_netmask; /* Netmask of interface */
  64     union {
  65         struct sockaddr *ifu_broadaddr;
  66                          /* Broadcast address of interface */
  67         struct sockaddr *ifu_dstaddr;
  68                          /* Point\-to\-point destination address */
  69     } ifa_ifu;
  70 #define              ifa_broadaddr ifa_ifu.ifu_broadaddr
  71 #define              ifa_dstaddr   ifa_ifu.ifu_dstaddr
  72     void            *ifa_data;    /* Address\-specific data */
  73 };
  74 .fi
  75 .in
  76 .PP
  77 The \fIifa_next\fP field contains a pointer to the next structure on the list,
  78 or NULL if this is the last item of the list.
  79 .PP
  80 .\" The constant
  81 .\" .B IF NAMESIZE
  82 .\" indicates the maximum length of this field.
  83 The \fIifa_name\fP points to the null\-terminated interface name.
  84 .PP
  85 The \fIifa_flags\fP field contains the interface flags, as returned by the
  86 \fBSIOCGIFFLAGS\fP \fBioctl\fP(2)  operation (see \fBnetdevice\fP(7)  for a list of
  87 these flags).
  88 .PP
  89 The \fIifa_addr\fP field points to a structure containing the interface
  90 address.  (The \fIsa_family\fP subfield should be consulted to determine the
  91 format of the address structure.)
  92 .PP
  93 The \fIifa_netmask\fP field points to a structure containing the netmask
  94 associated with \fIifa_addr\fP, if applicable for the address family.
  95 .PP
  96 Depending on whether the bit \fBIFF_BROADCAST\fP or \fBIFF_POINTOPOINT\fP is set
  97 in \fIifa_flags\fP (only one can be set at a time), either \fIifa_broadaddr\fP
  98 will contain the broadcast address associated with \fIifa_addr\fP (if
  99 applicable for the address family) or \fIifa_dstaddr\fP will contain the
 100 destination address of the point\-to\-point interface.
 101 .PP
 102 The \fIifa_data\fP field points to a buffer containing address\-family\-specific
 103 data; this field may be NULL if there is no such data for this interface.
 104 .PP
 105 The data returned by \fBgetifaddrs\fP()  is dynamically allocated and should be
 106 freed using \fBfreeifaddrs\fP()  when no longer needed.
 107 .SH 返り値
 108 On success, \fBgetifaddrs\fP()  returns zero; on error, \-1 is returned, and
 109 \fIerrno\fP is set appropriately.
 110 .SH エラー
 111 \fBgetifaddrs\fP()  may fail and set \fIerrno\fP for any of the errors specified
 112 for \fBsocket\fP(2), \fBbind\fP(2), \fBgetsockname\fP(2), \fBrecvmsg\fP(2),
 113 \fBsendto\fP(2), \fBmalloc\fP(3), or \fBrealloc\fP(3).
 114 .SH バージョン
 115 The \fBgetifaddrs\fP()  function first appeared in glibc 2.3, but before glibc
 116 2.3.3, the implementation only supported IPv4 addresses; IPv6 support was
 117 added in glibc 2.3.3.  Support of address families other than IPv4 is only
 118 available on kernels that support 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 Not in POSIX.1\-2001.  This function first appeared in BSDi and is present on
 125 the BSD systems, but with slightly different semantics
 126 documented\(emreturning one entry per interface, not per address.  This
 127 means \fIifa_addr\fP and other fields can actually be NULL if the interface has
 128 no address, and no link\-level address is returned if the interface has an IP
 129 address assigned.  Also, the way of choosing either \fIifa_broadaddr\fP or
 130 \fIifa_dstaddr\fP differs on various systems.
 131 .SH 注意
 132 The addresses returned on Linux will usually be the IPv4 and IPv6 addresses
 133 assigned to the interface, but also one \fBAF_PACKET\fP address per interface
 134 containing lower\-level details about the interface and its physical layer.
 135 In this case, the \fIifa_data\fP field may contain a pointer to a \fIstruct
 136 net_device_stats\fP, defined in \fI<linux/netdevice.h>\fP, which contains
 137 various interface attributes and statistics.
 138 .SH 例
 139 The program below demonstrates the use of \fBgetifaddrs\fP(), \fBfreeifaddrs\fP(),
 140 and \fBgetnameinfo\fP(3).  Here is what we see when running this program on one
 141 system:
 142 .in +4n
 143 .nf
 144
 145 $ \fB./a.out\fP
 146 lo      address family: 17 (AF_PACKET)
 147 eth0    address family: 17 (AF_PACKET)
 148 lo      address family: 2 (AF_INET)
 149         address: <127.0.0.1>
 150 eth0    address family: 2 (AF_INET)
 151         address: <10.1.1.4>
 152 lo      address family: 10 (AF_INET6)
 153         address: <::1>
 154 eth0    address family: 10 (AF_INET6)
 155         address: <fe80::2d0:59ff:feda:eb51%eth0>
 156 .fi
 157 .in
 158 .SS "Program source"
 159 \&
 160 .nf
 161 #include <arpa/inet.h>
 162 #include <sys/socket.h>
 163 #include <netdb.h>
 164 #include <ifaddrs.h>
 165 #include <stdio.h>
 166 #include <stdlib.h>
 167 #include <unistd.h>
 168
 169 int
 170 main(int argc, char *argv[])
 171 {
 172     struct ifaddrs *ifaddr, *ifa;
 173     int family, s;
 174     char host[NI_MAXHOST];
 175
 176     if (getifaddrs(&ifaddr) == \-1) {
 177         perror("getifaddrs");
 178         exit(EXIT_FAILURE);
 179     }
 180
 181     /* Walk through linked list, maintaining head pointer so we
 182        can free list later */
 183
 184     for (ifa = ifaddr; ifa != NULL; ifa = ifa\->ifa_next) {
 185         if (ifa\->ifa_addr == NULL)
 186             continue;
 187
 188         family = ifa\->ifa_addr\->sa_family;
 189
 190         /* Display interface name and family (including symbolic
 191            form of the latter for the common families) */
 192
 193         printf("%s\t  address family: %d%s\en",
 194                 ifa\->ifa_name, family,
 195                 (family == AF_PACKET) ? " (AF_PACKET)" :
 196                 (family == AF_INET) ?   " (AF_INET)" :
 197                 (family == AF_INET6) ?  " (AF_INET6)" : "");
 198
 199         /* For an AF_INET* interface address, display the address */
 200
 201         if (family == AF_INET || family == AF_INET6) {
 202             s = getnameinfo(ifa\->ifa_addr,
 203                     (family == AF_INET) ? sizeof(struct sockaddr_in) :
 204                                           sizeof(struct sockaddr_in6),
 205                     host, NI_MAXHOST, NULL, 0, NI_NUMERICHOST);
 206             if (s != 0) {
 207                 printf("getnameinfo() failed: %s\en", gai_strerror(s));
 208                 exit(EXIT_FAILURE);
 209             }
 210             printf("\etaddress: <%s>\en", host);
 211         }
 212     }
 213
 214     freeifaddrs(ifaddr);
 215     exit(EXIT_SUCCESS);
 216 }
 217 .fi
 218 .SH 関連項目
 219 \fBbind\fP(2), \fBgetsockname\fP(2), \fBsocket\fP(2), \fBpacket\fP(7), \fBifconfig\fP(8)