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 2019-03-06 "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 .PP
  44 .BI "int getifaddrs(struct ifaddrs **" "ifap" );
  45 .PP
  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 .PP
  59 .in +4n
  60 .EX
  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 .EE
  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 ATTRIBUTES
 171 For an explanation of the terms used in this section, see
 172 .BR attributes (7).
 173 .TS
 174 allbox;
 175 lbw27 lb lb
 176 l l l.
 177 Interface       Attribute       Value
 178 T{
 179 .BR getifaddrs (),
 180 .BR freeifaddrs ()
 181 T}      Thread safety   MT-Safe
 182 .TE
 183 .sp 1
 184 .SH CONFORMING TO
 185 Not in POSIX.1.
 186 This function first appeared in BSDi and is
 187 present on the BSD systems, but with slightly different
 188 semantics documented\(emreturning one entry per interface,
 189 not per address.
 190 This means
 191 .I ifa_addr
 192 and other fields can actually be NULL if the interface has no address,
 193 and no link-level address is returned if the interface has an IP address
 194 assigned.
 195 Also, the way of choosing either
 196 .I ifa_broadaddr
 197 or
 198 .I ifa_dstaddr
 199 differs on various systems.
 200 .\" , but the BSD-derived documentation generally
 201 .\" appears to be confused and obsolete on this point.
 202 .\" i.e., commonly it still says one of them will be NULL, even if
 203 .\" the ifa_ifu union is already present
 204 .SH NOTES
 205 The addresses returned on Linux will usually be the IPv4 and IPv6 addresses
 206 assigned to the interface, but also one
 207 .B AF_PACKET
 208 address per interface containing lower-level details about the interface
 209 and its physical layer.
 210 In this case, the
 211 .I ifa_data
 212 field may contain a pointer to a
 213 .IR "struct rtnl_link_stats" ,
 214 defined in
 215 .IR <linux/if_link.h>
 216 (in Linux 2.4 and earlier,
 217 .IR "struct net_device_stats" ,
 218 defined in
 219 .IR <linux/netdevice.h> ),
 220 which contains various interface attributes and statistics.
 221 .SH EXAMPLE
 222 The program below demonstrates the use of
 223 .BR getifaddrs (),
 224 .BR freeifaddrs (),
 225 and
 226 .BR getnameinfo (3).
 227 Here is what we see when running this program on one system:
 228 .PP
 229 .in +4n
 230 .EX
 231 $ \fB./a.out\fP
 232 lo       AF_PACKET (17)
 233                 tx_packets =        524; rx_packets =        524
 234                 tx_bytes   =      38788; rx_bytes   =      38788
 235 wlp3s0   AF_PACKET (17)
 236                 tx_packets =     108391; rx_packets =     130245
 237                 tx_bytes   =   30420659; rx_bytes   =   94230014
 238 em1      AF_PACKET (17)
 239                 tx_packets =          0; rx_packets =          0
 240                 tx_bytes   =          0; rx_bytes   =          0
 241 lo       AF_INET (2)
 242                 address: <127.0.0.1>
 243 wlp3s0   AF_INET (2)
 244                 address: <192.168.235.137>
 245 lo       AF_INET6 (10)
 246                 address: <::1>
 247 wlp3s0   AF_INET6 (10)
 248                 address: <fe80::7ee9:d3ff:fef5:1a91%wlp3s0>
 249 .EE
 250 .in
 251 .SS Program source
 252 \&
 253 .EX
 254 #define _GNU_SOURCE     /* To get defns of NI_MAXSERV and NI_MAXHOST */
 255 #include <arpa/inet.h>
 256 #include <sys/socket.h>
 257 #include <netdb.h>
 258 #include <ifaddrs.h>
 259 #include <stdio.h>
 260 #include <stdlib.h>
 261 #include <unistd.h>
 262 #include <linux/if_link.h>
 263
 264 int main(int argc, char *argv[])
 265 {
 266     struct ifaddrs *ifaddr, *ifa;
 267     int family, s, n;
 268     char host[NI_MAXHOST];
 269
 270     if (getifaddrs(&ifaddr) == \-1) {
 271         perror("getifaddrs");
 272         exit(EXIT_FAILURE);
 273     }
 274
 275     /* Walk through linked list, maintaining head pointer so we
 276        can free list later */
 277
 278     for (ifa = ifaddr, n = 0; ifa != NULL; ifa = ifa\->ifa_next, n++) {
 279         if (ifa\->ifa_addr == NULL)
 280             continue;
 281
 282         family = ifa\->ifa_addr\->sa_family;
 283
 284         /* Display interface name and family (including symbolic
 285            form of the latter for the common families) */
 286
 287         printf("%\-8s %s (%d)\en",
 288                ifa\->ifa_name,
 289                (family == AF_PACKET) ? "AF_PACKET" :
 290                (family == AF_INET) ? "AF_INET" :
 291                (family == AF_INET6) ? "AF_INET6" : "???",
 292                family);
 293
 294         /* For an AF_INET* interface address, display the address */
 295
 296         if (family == AF_INET || family == AF_INET6) {
 297             s = getnameinfo(ifa\->ifa_addr,
 298                     (family == AF_INET) ? sizeof(struct sockaddr_in) :
 299                                           sizeof(struct sockaddr_in6),
 300                     host, NI_MAXHOST,
 301                     NULL, 0, NI_NUMERICHOST);
 302             if (s != 0) {
 303                 printf("getnameinfo() failed: %s\en", gai_strerror(s));
 304                 exit(EXIT_FAILURE);
 305             }
 306
 307             printf("\et\etaddress: <%s>\en", host);
 308
 309         } else if (family == AF_PACKET && ifa\->ifa_data != NULL) {
 310             struct rtnl_link_stats *stats = ifa\->ifa_data;
 311
 312             printf("\et\ettx_packets = %10u; rx_packets = %10u\en"
 313                    "\et\ettx_bytes   = %10u; rx_bytes   = %10u\en",
 314                    stats\->tx_packets, stats\->rx_packets,
 315                    stats\->tx_bytes, stats\->rx_bytes);
 316         }
 317     }
 318
 319     freeifaddrs(ifaddr);
 320     exit(EXIT_SUCCESS);
 321 }
 322 .EE
 323 .SH SEE ALSO
 324 .BR bind (2),
 325 .BR getsockname (2),
 326 .BR socket (2),
 327 .BR packet (7),
 328 .BR ifconfig (8)