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 .TH GETIFADDRS 3 2009-01-14 "GNU" "Linux Programmer's Manual"
  34 .\" FIXME Make a link for freeifaddrs.3
  35 .\" FIXME Check other changes in Petr's mail
  36 .SH NAME
  37 getifaddrs, freeifaddrs \- get interface addresses
  38 .SH SYNOPSIS
  39 .nf
  40 .B #include <sys/types.h>
  41 .B #include <ifaddrs.h>
  42 .sp
  43 .BI "int getifaddrs(struct ifaddrs **" "ifap" );
  44 .sp
  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 .sp
  58 .in +4n
  59 .nf
  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 .fi
  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 sub-field should be consulted to determine the format of the
 106 address structure.)
 107 .PP
 108 The
 109 .I ifa_netmask
 110 field points to a structure containing the netmask associated with
 111 .IR ifa_addr ,
 112 if applicable for the address family.
 113 .PP
 114 Depending on whether the bit
 115 .B IFF_BROADCAST
 116 or
 117 .B IFF_POINTOPOINT
 118 is set in
 119 .I ifa_flags
 120 (only one can be set at a time),
 121 either
 122 .I ifa_broadaddr
 123 will contain the broadcast address associated with
 124 .I ifa_addr
 125 (if applicable for the address family) or
 126 .I ifa_dstaddr
 127 will contain the destination address of the point-to-point interface.
 128 .PP
 129 The
 130 .I ifa_data
 131 field points to a buffer containing address-family-specific data;
 132 this field may be NULL if there is no such data for this interface.
 133 .PP
 134 The data returned by
 135 .BR getifaddrs ()
 136 is dynamically allocated and should be freed using
 137 .BR freeifaddrs ()
 138 when no longer needed.
 139 .SH RETURN VALUES
 140 On success,
 141 .BR getifaddrs ()
 142 returns zero;
 143 on error, -1 is returned, and
 144 .I errno
 145 is set appropriately.
 146 .SH ERRORS
 147 .BR getifaddrs ()
 148 may fail and set
 149 .I errno
 150 for any of the errors specified for
 151 .BR socket (2),
 152 .BR bind (2),
 153 .\" FIXME Petr, I added getsockname() and recvmsg(); do you agree?
 154 .BR getsockname (2),
 155 .BR recvmsg (2),
 156 .BR sendto (2),
 157 .BR malloc (3),
 158 or
 159 .BR realloc (3).
 160 .SH VERSIONS
 161 The
 162 .BR getifaddrs ()
 163 function first appeared in glibc 2.3, but before glibc 2.3.3,
 164 the implementation only supported IPv4 addresses;
 165 IPv6 support was added in glibc 2.3.3.
 166 .SH CONFORMING TO
 167 Not in POSIX.1-2001.
 168 This function first appeared in BSDi and is
 169 present on the BSD systems, but with slightly different
 170 semantics documented\(emreturning one entry per interface,
 171 not per address.
 172 This means
 173 .I ifa_addr
 174 and other fields can actually be NULL if the interface has no address,
 175 and no link-level address is returned if the interface has an IP address
 176 assigned.
 177 Also, the way of choosing either
 178 .I ifa_broadaddr
 179 or
 180 .I ifa_dstaddr
 181 differs on various systems.
 182 .\" , but the BSD-derived documentation generally
 183 .\" appears to be confused and obsolete on this point.
 184 .\" i.e., commonly it still says one of them will be NULL, even if
 185 .\" the ifa_ifu union is already present
 186 .SH NOTES
 187 The addresses returned on Linux will usually be the IPv4 and IPv6 addresses
 188 assigned to the interface, but also one
 189 .B AF_PACKET
 190 address per interface containing lower-level details about the interface
 191 and its physical layer.
 192 In this case, the
 193 .I ifa_data
 194 field may contain a pointer to a
 195 .IR "struct net_device_stats" ,
 196 defined in
 197 .IR <linux/netdevice.h> ,
 198 which contains various interface attributes and statistics.
 199 .SH EXAMPLE
 200 The program below demonstrates the use of
 201 .BR getifaddrs (),
 202 .BR freeifaddrs (),
 203 and
 204 .BR inet_ntop (3).
 205 Here is what we see when running this program on one system:
 206 .in +4n
 207 .nf
 208
 209 $ \fB./a.out\fP
 210 lo      address family: 17 (AF_PACKET)
 211 eth0    address family: 17 (AF_PACKET)
 212 lo      address family: 2 (AF_INET)
 213         address: <127.0.0.1>
 214 eth0    address family: 2 (AF_INET)
 215         address: <10.1.1.4>
 216 lo      address family: 10 (AF_INET6)
 217         address: <::1>
 218 eth0    address family: 10 (AF_INET6)
 219         address: <fe80::2d0:59ff:feda:eb51%eth0>
 220 .fi
 221 .in
 222 .SS Program source
 223 \&
 224 .nf
 225 #include <arpa/inet.h>
 226 #include <sys/socket.h>
 227 #include <netdb.h>
 228 #include <ifaddrs.h>
 229 #include <stdio.h>
 230 #include <stdlib.h>
 231 #include <unistd.h>
 232
 233 int
 234 main(int argc, char *argv[])
 235 {
 236     struct ifaddrs *ifaddr;
 237     struct net_device_stats *ndsp;
 238     int family, s;
 239     char host[NI_MAXHOST];
 240
 241     if (getifaddrs(&ifaddr) == \-1) {
 242         perror("getifaddrs");
 243         exit(EXIT_FAILURE);
 244     }
 245
 246     while (ifaddr != NULL) {    /* Walk through linked list */
 247         family = ifaddr\->ifa_addr\->sa_family;
 248
 249         /* Display interface name and family (including symbolic
 250            form of the latter for the common families) */
 251
 252         printf("%\-6s  address family: %d%s\\n",
 253                 ifaddr\->ifa_name, family,
 254                 (family == AF_PACKET) ? " (AF_PACKET)" :
 255                 (family == AF_INET) ?   " (AF_INET)" :
 256                 (family == AF_INET6) ?  " (AF_INET6)" : "");
 257
 258         /* For an AF_INET* interface address, display the address */
 259
 260         if (family == AF_INET || family == AF_INET6) {
 261             s = getnameinfo(ifaddr\->ifa_addr,
 262                     (family == AF_INET) ? sizeof(struct sockaddr_in) :
 263                                           sizeof(struct sockaddr_in6),
 264                     host, NI_MAXHOST, NULL, 0, NI_NUMERICHOST);
 265             if (s != 0) {
 266                 printf("getnameinfo() failed: %s\\n", gai_strerror(s));
 267                 exit(EXIT_FAILURE);
 268             }
 269             printf("\\taddress: <%s>\\n", host);
 270         }
 271
 272         ifaddr = ifaddr\->ifa_next;
 273     }
 274
 275     freeifaddrs(ifaddr);
 276     exit(EXIT_SUCCESS);
 277 }
 278 .fi
 279 .SH SEE ALSO
 280 .BR bind (2),
 281 .BR getsockname (2),
 282 .BR socket (2),
 283 .BR packet (7),
 284 .BR ifconfig (8)