original/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 .TH GETIFADDRS 3 2014-02-26 "GNU" "Linux Programmer's Manual"
  37 .SH NAME
  38 getifaddrs, freeifaddrs \- get interface addresses
  39 .SH SYNOPSIS
  40 .nf
  41 .B #include <sys/types.h>
  42 .B #include <ifaddrs.h>
  43 .sp
  44 .BI "int getifaddrs(struct ifaddrs **" "ifap" );
  45 .sp
  46 .BI "void freeifaddrs(struct ifaddrs *" "ifa" );
  47 .fi
  48 .SH DESCRIPTION
  49 The
  50 .BR getifaddrs ()
  51 function creates a linked list of structures describing
  52 the network interfaces of the local system,
  53 and stores the address of the first item of the list in
  54 .IR *ifap .
  55 The list consists of
  56 .I ifaddrs
  57 structures, defined as follows:
  58 .sp
  59 .in +4n
  60 .nf
  61 struct ifaddrs {
  62     struct ifaddrs  *ifa_next;    /* Next item in list */
  63     char            *ifa_name;    /* Name of interface */
  64     unsigned int     ifa_flags;   /* Flags from SIOCGIFFLAGS */
  65     struct sockaddr *ifa_addr;    /* Address of interface */
  66     struct sockaddr *ifa_netmask; /* Netmask of interface */
  67     union {
  68         struct sockaddr *ifu_broadaddr;
  69                          /* Broadcast address of interface */
  70         struct sockaddr *ifu_dstaddr;
  71                          /* Point-to-point destination address */
  72     } ifa_ifu;
  73 #define              ifa_broadaddr ifa_ifu.ifu_broadaddr
  74 #define              ifa_dstaddr   ifa_ifu.ifu_dstaddr
  75     void            *ifa_data;    /* Address-specific data */
  76 };
  77 .fi
  78 .in
  79 .PP
  80 The
  81 .I ifa_next
  82 field contains a pointer to the next structure on the list,
  83 or NULL if this is the last item of the list.
  84 .PP
  85 The
  86 .I ifa_name
  87 points to the null-terminated interface name.
  88 .\" The constant
  89 .\" .B IF NAMESIZE
  90 .\" indicates the maximum length of this field.
  91 .PP
  92 The
  93 .I ifa_flags
  94 field contains the interface flags, as returned by the
  95 .B SIOCGIFFLAGS
  96 .BR ioctl (2)
  97 operation (see
  98 .BR netdevice (7)
  99 for a list of these flags).
 100 .PP
 101 The
 102 .I ifa_addr
 103 field points to a structure containing the interface address.
 104 (The
 105 .I sa_family
 106 subfield should be consulted to determine the format of the
 107 address structure.)
 108 This field may contain a null pointer.
 109 .PP
 110 The
 111 .I ifa_netmask
 112 field points to a structure containing the netmask associated with
 113 .IR ifa_addr ,
 114 if applicable for the address family.
 115 This field may contain a null pointer.
 116 .PP
 117 Depending on whether the bit
 118 .B IFF_BROADCAST
 119 or
 120 .B IFF_POINTOPOINT
 121 is set in
 122 .I ifa_flags
 123 (only one can be set at a time),
 124 either
 125 .I ifa_broadaddr
 126 will contain the broadcast address associated with
 127 .I ifa_addr
 128 (if applicable for the address family) or
 129 .I ifa_dstaddr
 130 will contain the destination address of the point-to-point interface.
 131 .PP
 132 The
 133 .I ifa_data
 134 field points to a buffer containing address-family-specific data;
 135 this field may be NULL if there is no such data for this interface.
 136 .PP
 137 The data returned by
 138 .BR getifaddrs ()
 139 is dynamically allocated and should be freed using
 140 .BR freeifaddrs ()
 141 when no longer needed.
 142 .SH RETURN VALUE
 143 On success,
 144 .BR getifaddrs ()
 145 returns zero;
 146 on error, \-1 is returned, and
 147 .I errno
 148 is set appropriately.
 149 .SH ERRORS
 150 .BR getifaddrs ()
 151 may fail and set
 152 .I errno
 153 for any of the errors specified for
 154 .BR socket (2),
 155 .BR bind (2),
 156 .BR getsockname (2),
 157 .BR recvmsg (2),
 158 .BR sendto (2),
 159 .BR malloc (3),
 160 or
 161 .BR realloc (3).
 162 .SH VERSIONS
 163 The
 164 .BR getifaddrs ()
 165 function first appeared in glibc 2.3, but before glibc 2.3.3,
 166 the implementation supported only IPv4 addresses;
 167 IPv6 support was added in glibc 2.3.3.
 168 Support of address families other than IPv4 is available only
 169 on kernels that support netlink.
 170 .SH CONFORMING TO
 171 Not in POSIX.1-2001.
 172 This function first appeared in BSDi and is
 173 present on the BSD systems, but with slightly different
 174 semantics documented\(emreturning one entry per interface,
 175 not per address.
 176 This means
 177 .I ifa_addr
 178 and other fields can actually be NULL if the interface has no address,
 179 and no link-level address is returned if the interface has an IP address
 180 assigned.
 181 Also, the way of choosing either
 182 .I ifa_broadaddr
 183 or
 184 .I ifa_dstaddr
 185 differs on various systems.
 186 .\" , but the BSD-derived documentation generally
 187 .\" appears to be confused and obsolete on this point.
 188 .\" i.e., commonly it still says one of them will be NULL, even if
 189 .\" the ifa_ifu union is already present
 190 .SH NOTES
 191 The addresses returned on Linux will usually be the IPv4 and IPv6 addresses
 192 assigned to the interface, but also one
 193 .B AF_PACKET
 194 address per interface containing lower-level details about the interface
 195 and its physical layer.
 196 In this case, the
 197 .I ifa_data
 198 field may contain a pointer to a
 199 .IR "struct rtnl_link_stats" ,
 200 defined in
 201 .IR <linux/if_link.h>
 202 (in Linux 2.4 and earlier,
 203 .IR "struct net_device_stats" ,
 204 defined in
 205 .IR <linux/netdevice.h> ),
 206 which contains various interface attributes and statistics.
 207 .SH EXAMPLE
 208 The program below demonstrates the use of
 209 .BR getifaddrs (),
 210 .BR freeifaddrs (),
 211 and
 212 .BR getnameinfo (3).
 213 Here is what we see when running this program on one system:
 214 .in +4n
 215 .nf
 216
 217 $ \fB./a.out\fP
 218 lo       AF_PACKET (17)
 219                 tx_packets =        524; rx_packets =        524
 220                 tx_bytes   =      38788; rx_bytes   =      38788
 221 wlp3s0   AF_PACKET (17)
 222                 tx_packets =     108391; rx_packets =     130245
 223                 tx_bytes   =   30420659; rx_bytes   =   94230014
 224 em1      AF_PACKET (17)
 225                 tx_packets =          0; rx_packets =          0
 226                 tx_bytes   =          0; rx_bytes   =          0
 227 lo       AF_INET (2)
 228                 address: <127.0.0.1>
 229 wlp3s0   AF_INET (2)
 230                 address: <192.168.235.137>
 231 lo       AF_INET6 (10)
 232                 address: <::1>
 233 wlp3s0   AF_INET6 (10)
 234                 address: <fe80::7ee9:d3ff:fef5:1a91%wlp3s0>
 235 .fi
 236 .in
 237 .SS Program source
 238 \&
 239 .nf
 240 #define _GNU_SOURCE     /* To get defns of NI_MAXSERV and NI_MAXHOST */
 241 #include <arpa/inet.h>
 242 #include <sys/socket.h>
 243 #include <netdb.h>
 244 #include <ifaddrs.h>
 245 #include <stdio.h>
 246 #include <stdlib.h>
 247 #include <unistd.h>
 248 #include <linux/if_link.h>
 249
 250 int main(int argc, char *argv[])
 251 {
 252     struct ifaddrs *ifaddr, *ifa;
 253     int family, s, n;
 254     char host[NI_MAXHOST];
 255
 256     if (getifaddrs(&ifaddr) == \-1) {
 257         perror("getifaddrs");
 258         exit(EXIT_FAILURE);
 259     }
 260
 261     /* Walk through linked list, maintaining head pointer so we
 262        can free list later */
 263
 264     for (ifa = ifaddr, n = 0; ifa != NULL; ifa = ifa\->ifa_next, n++) {
 265         if (ifa\->ifa_addr == NULL)
 266             continue;
 267
 268         family = ifa\->ifa_addr\->sa_family;
 269
 270         /* Display interface name and family (including symbolic
 271            form of the latter for the common families) */
 272
 273         printf("%\-8s %s (%d)\\n",
 274                ifa\->ifa_name,
 275                (family == AF_PACKET) ? "AF_PACKET" :
 276                (family == AF_INET) ? "AF_INET" :
 277                (family == AF_INET6) ? "AF_INET6" : "???",
 278                family);
 279
 280         /* For an AF_INET* interface address, display the address */
 281
 282         if (family == AF_INET || family == AF_INET6) {
 283             s = getnameinfo(ifa\->ifa_addr,
 284                     (family == AF_INET) ? sizeof(struct sockaddr_in) :
 285                                           sizeof(struct sockaddr_in6),
 286                     host, NI_MAXHOST,
 287                     NULL, 0, NI_NUMERICHOST);
 288             if (s != 0) {
 289                 printf("getnameinfo() failed: %s\\n", gai_strerror(s));
 290                 exit(EXIT_FAILURE);
 291             }
 292
 293             printf("\\t\\taddress: <%s>\\n", host);
 294
 295         } else if (family == AF_PACKET && ifa\->ifa_data != NULL) {
 296             struct rtnl_link_stats *stats = ifa\->ifa_data;
 297
 298             printf("\\t\\ttx_packets = %10u; rx_packets = %10u\\n"
 299                    "\\t\\ttx_bytes   = %10u; rx_bytes   = %10u\\n",
 300                    stats\->tx_packets, stats\->rx_packets,
 301                    stats\->tx_bytes, stats\->rx_bytes);
 302         }
 303     }
 304
 305     freeifaddrs(ifaddr);
 306     exit(EXIT_SUCCESS);
 307 }
 308 .fi
 309 .SH SEE ALSO
 310 .BR bind (2),
 311 .BR getsockname (2),
 312 .BR socket (2),
 313 .BR packet (7),
 314 .BR ifconfig (8)
 315 .SH COLOPHON
 316 This page is part of release 3.79 of the Linux
 317 .I man-pages
 318 project.
 319 A description of the project,
 320 information about reporting bugs,
 321 and the latest version of this page,
 322 can be found at
 323 \%http://www.kernel.org/doc/man\-pages/.