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