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