1.\" $KAME: getifaddrs.3,v 1.4 2000/05/17 14:13:14 itojun Exp $ 2.\" BSDI getifaddrs.3,v 2.5 2000/02/23 14:51:59 dab Exp 3.\" 4.\" Copyright (c) 1995, 1999 5.\" Berkeley Software Design, Inc. All rights reserved. 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.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY Berkeley Software Design, Inc. ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL Berkeley Software Design, Inc. BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD: src/lib/libc/net/getifaddrs.3,v 1.10 2005/02/09 18:03:13 ru Exp $ 26.\" 27.Dd September 12, 2019 28.Dt GETIFADDRS 3 29.Os 30.Sh NAME 31.Nm getifaddrs 32.Nd get interface addresses 33.Sh LIBRARY 34.Lb libc 35.Sh SYNOPSIS 36.In sys/types.h 37.In sys/socket.h 38.In ifaddrs.h 39.Ft int 40.Fn getifaddrs "struct ifaddrs **ifap" 41.Ft void 42.Fn freeifaddrs "struct ifaddrs *ifp" 43.Sh DESCRIPTION 44The 45.Fn getifaddrs 46function stores a reference to a linked list of the network interfaces 47on the local machine in the memory referenced by 48.Fa ifap . 49The list consists of 50.Nm ifaddrs 51structures, as defined in the include file 52.In ifaddrs.h . 53The 54.Nm ifaddrs 55structure contains at least the following entries: 56.Bd -literal 57 struct ifaddrs *ifa_next; /* Pointer to next struct */ 58 char *ifa_name; /* Interface name */ 59 u_int ifa_flags; /* Interface flags */ 60 struct sockaddr *ifa_addr; /* Interface address */ 61 struct sockaddr *ifa_netmask; /* Interface netmask */ 62 struct sockaddr *ifa_dstaddr; /* P2P interface destination */ 63 void *ifa_data; /* Address specific data */ 64 u_int ifa_addrflags; /* Family specific address flags */ 65.Ed 66.Pp 67The 68.Fa ifa_next 69field contains a pointer to the next structure on the list. 70This field is 71.Dv NULL 72in last structure on the list. 73.Pp 74The 75.Fa ifa_name 76field contains the interface name. 77.Pp 78The 79.Fa ifa_flags 80field contains the interface flags, as set by 81.Xr ifconfig 8 82utility. 83.Pp 84The 85.Fa ifa_addr 86field references either the address of the interface or the link level 87address of the interface, if one exists, otherwise it is NULL. 88(The 89.Fa sa_family 90field of the 91.Fa ifa_addr 92field should be consulted to determine the format of the 93.Fa ifa_addr 94address.) 95.Pp 96The 97.Fa ifa_netmask 98field references the netmask associated with 99.Fa ifa_addr , 100if one is set, otherwise it is NULL. 101.Pp 102The 103.Fa ifa_dstaddr 104field references the destination address on a P2P interface, 105if one exists, otherwise it is NULL. 106.Pp 107The 108.Fa ifa_broadaddr 109field, 110which should only be referenced for non-P2P interfaces, 111references the broadcast address associated with 112.Fa ifa_addr , 113if one exists, otherwise it is NULL. 114It is really just another name for 115.Fa ifa_dstaddr . 116.Pp 117The 118.Fa ifa_addrflags 119field contains the address flags, which are specific to the address family. 120.Pp 121The 122.Fa ifa_data 123field references address family specific data. 124For 125.Dv AF_LINK 126addresses it contains a pointer to the 127.Vt struct if_data 128(as defined in include file 129.In net/if.h ) 130which contains various interface attributes and statistics. 131For all other address families, it contains a pointer to the 132.Vt struct ifa_data 133(as defined in include file 134.In net/if.h ) 135which contains per-address interface statistics. 136.Pp 137The data returned by 138.Fn getifaddrs 139is dynamically allocated and should be freed using 140.Fn freeifaddrs 141when no longer needed. 142.Sh RETURN VALUES 143.Rv -std getifaddrs 144.Sh ERRORS 145The 146.Fn getifaddrs 147may fail and set 148.Va errno 149for any of the errors specified for the library routines 150.Xr ioctl 2 , 151.Xr socket 2 , 152.Xr malloc 3 153or 154.Xr sysctl 3 . 155.Sh SEE ALSO 156.Xr ioctl 2 , 157.Xr socket 2 , 158.Xr sysctl 3 , 159.Xr networking 4 , 160.Xr ifconfig 8 161.Sh HISTORY 162The 163.Nm 164implementation first appeared in BSDi 165.Bsx . 166.Pp 167.Fa if_addrflags 168was added in 169.Nx 8.0 . 170.Sh BUGS 171If both 172.In net/if.h 173and 174.In ifaddrs.h 175are being included, 176.In net/if.h 177.Em must 178be included before 179.In ifaddrs.h . 180