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