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 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 2008-12-08 Petr Baudis <pasky@suse.cz>
  12 .\"    Rewrite the BSD manpage in the Linux man pages style and account
  13 .\"    for glibc specificities, provide an example.
  14 .\" 2009-01-14 mtk, many edits and changes, rewrote example program.
  15 .\"
  16 .TH GETIFADDRS 3 (date) "Linux man-pages (unreleased)"
  17 .SH NAME
  18 getifaddrs, freeifaddrs \- get interface addresses
  19 .SH LIBRARY
  20 Standard C library
  21 .RI ( libc ", " \-lc )
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <sys/types.h>
  25 .B #include <ifaddrs.h>
  26 .PP
  27 .BI "int getifaddrs(struct ifaddrs **" "ifap" );
  28 .BI "void freeifaddrs(struct ifaddrs *" "ifa" );
  29 .fi
  30 .SH DESCRIPTION
  31 The
  32 .BR getifaddrs ()
  33 function creates a linked list of structures describing
  34 the network interfaces of the local system,
  35 and stores the address of the first item of the list in
  36 .IR *ifap .
  37 The list consists of
  38 .I ifaddrs
  39 structures, defined as follows:
  40 .PP
  41 .in +4n
  42 .EX
  43 struct ifaddrs {
  44     struct ifaddrs  *ifa_next;    /* Next item in list */
  45     char            *ifa_name;    /* Name of interface */
  46     unsigned int     ifa_flags;   /* Flags from SIOCGIFFLAGS */
  47     struct sockaddr *ifa_addr;    /* Address of interface */
  48     struct sockaddr *ifa_netmask; /* Netmask of interface */
  49     union {
  50         struct sockaddr *ifu_broadaddr;
  51                          /* Broadcast address of interface */
  52         struct sockaddr *ifu_dstaddr;
  53                          /* Point\-to\-point destination address */
  54     } ifa_ifu;
  55 #define              ifa_broadaddr ifa_ifu.ifu_broadaddr
  56 #define              ifa_dstaddr   ifa_ifu.ifu_dstaddr
  57     void            *ifa_data;    /* Address\-specific data */
  58 };
  59 .EE
  60 .in
  61 .PP
  62 The
  63 .I ifa_next
  64 field contains a pointer to the next structure on the list,
  65 or NULL if this is the last item of the list.
  66 .PP
  67 The
  68 .I ifa_name
  69 points to the null-terminated interface name.
  70 .\" The constant
  71 .\" .B IF NAMESIZE
  72 .\" indicates the maximum length of this field.
  73 .PP
  74 The
  75 .I ifa_flags
  76 field contains the interface flags, as returned by the
  77 .B SIOCGIFFLAGS
  78 .BR ioctl (2)
  79 operation (see
  80 .BR netdevice (7)
  81 for a list of these flags).
  82 .PP
  83 The
  84 .I ifa_addr
  85 field points to a structure containing the interface address.
  86 (The
  87 .I sa_family
  88 subfield should be consulted to determine the format of the
  89 address structure.)
  90 This field may contain a null pointer.
  91 .PP
  92 The
  93 .I ifa_netmask
  94 field points to a structure containing the netmask associated with
  95 .IR ifa_addr ,
  96 if applicable for the address family.
  97 This field may contain a null pointer.
  98 .PP
  99 Depending on whether the bit
 100 .B IFF_BROADCAST
 101 or
 102 .B IFF_POINTOPOINT
 103 is set in
 104 .I ifa_flags
 105 (only one can be set at a time),
 106 either
 107 .I ifa_broadaddr
 108 will contain the broadcast address associated with
 109 .I ifa_addr
 110 (if applicable for the address family) or
 111 .I ifa_dstaddr
 112 will contain the destination address of the point-to-point interface.
 113 .PP
 114 The
 115 .I ifa_data
 116 field points to a buffer containing address-family-specific data;
 117 this field may be NULL if there is no such data for this interface.
 118 .PP
 119 The data returned by
 120 .BR getifaddrs ()
 121 is dynamically allocated and should be freed using
 122 .BR freeifaddrs ()
 123 when no longer needed.
 124 .SH RETURN VALUE
 125 On success,
 126 .BR getifaddrs ()
 127 returns zero;
 128 on error, \-1 is returned, and
 129 .I errno
 130 is set to indicate the error.
 131 .SH ERRORS
 132 .BR getifaddrs ()
 133 may fail and set
 134 .I errno
 135 for any of the errors specified for
 136 .BR socket (2),
 137 .BR bind (2),
 138 .BR getsockname (2),
 139 .BR recvmsg (2),
 140 .BR sendto (2),
 141 .BR malloc (3),
 142 or
 143 .BR realloc (3).
 144 .SH VERSIONS
 145 The
 146 .BR getifaddrs ()
 147 function first appeared in glibc 2.3, but before glibc 2.3.3,
 148 the implementation supported only IPv4 addresses;
 149 IPv6 support was added in glibc 2.3.3.
 150 Support of address families other than IPv4 is available only
 151 on kernels that support netlink.
 152 .SH ATTRIBUTES
 153 For an explanation of the terms used in this section, see
 154 .BR attributes (7).
 155 .ad l
 156 .nh
 157 .TS
 158 allbox;
 159 lbx lb lb
 160 l l l.
 161 Interface       Attribute       Value
 162 T{
 163 .BR getifaddrs (),
 164 .BR freeifaddrs ()
 165 T}      Thread safety   MT-Safe
 166 .TE
 167 .hy
 168 .ad
 169 .sp 1
 170 .SH STANDARDS
 171 Not in POSIX.1.
 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 .I <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 EXAMPLES
 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 .PP
 215 .in +4n
 216 .EX
 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 .EE
 236 .in
 237 .SS Program source
 238 \&
 239 .EX
 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;
 253     int family, s;
 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 (struct ifaddrs *ifa = ifaddr; ifa != NULL;
 265              ifa = ifa\->ifa_next) {
 266         if (ifa\->ifa_addr == NULL)
 267             continue;
 268
 269         family = ifa\->ifa_addr\->sa_family;
 270
 271         /* Display interface name and family (including symbolic
 272            form of the latter for the common families). */
 273
 274         printf("%\-8s %s (%d)\en",
 275                ifa\->ifa_name,
 276                (family == AF_PACKET) ? "AF_PACKET" :
 277                (family == AF_INET) ? "AF_INET" :
 278                (family == AF_INET6) ? "AF_INET6" : "???",
 279                family);
 280
 281         /* For an AF_INET* interface address, display the address. */
 282
 283         if (family == AF_INET || family == AF_INET6) {
 284             s = getnameinfo(ifa\->ifa_addr,
 285                     (family == AF_INET) ? sizeof(struct sockaddr_in) :
 286                                           sizeof(struct sockaddr_in6),
 287                     host, NI_MAXHOST,
 288                     NULL, 0, NI_NUMERICHOST);
 289             if (s != 0) {
 290                 printf("getnameinfo() failed: %s\en", gai_strerror(s));
 291                 exit(EXIT_FAILURE);
 292             }
 293
 294             printf("\et\etaddress: <%s>\en", host);
 295
 296         } else if (family == AF_PACKET && ifa\->ifa_data != NULL) {
 297             struct rtnl_link_stats *stats = ifa\->ifa_data;
 298
 299             printf("\et\ettx_packets = %10u; rx_packets = %10u\en"
 300                    "\et\ettx_bytes   = %10u; rx_bytes   = %10u\en",
 301                    stats\->tx_packets, stats\->rx_packets,
 302                    stats\->tx_bytes, stats\->rx_bytes);
 303         }
 304     }
 305
 306     freeifaddrs(ifaddr);
 307     exit(EXIT_SUCCESS);
 308 }
 309 .EE
 310 .SH SEE ALSO
 311 .BR bind (2),
 312 .BR getsockname (2),
 313 .BR socket (2),
 314 .BR packet (7),
 315 .BR ifconfig (8)