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.4 2006/05/26 19:39:37 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 SYNOPSIS 33.In sys/types.h 34.In sys/socket.h 35.In ifaddrs.h 36.Ft int 37.Fn getifaddrs "struct ifaddrs **ifap" 38.Ft void 39.Fn freeifaddrs "struct ifaddrs *ifp" 40.Sh DESCRIPTION 41The 42.Fn getifaddrs 43function stores a reference to a linked list of the network interfaces 44on the local machine in the memory referenced by 45.Fa ifap . 46The list consists of 47.Nm ifaddrs 48structures, as defined in the include file 49.In ifaddrs.h . 50The 51.Nm ifaddrs 52structure contains at least the following entries: 53.Bd -literal 54 struct ifaddrs *ifa_next; /* Pointer to next struct */ 55 char *ifa_name; /* Interface name */ 56 u_int ifa_flags; /* Interface flags */ 57 struct sockaddr *ifa_addr; /* Interface address */ 58 struct sockaddr *ifa_netmask; /* Interface netmask */ 59 struct sockaddr *ifa_broadaddr; /* Interface broadcast address */ 60 struct sockaddr *ifa_dstaddr; /* P2P interface destination */ 61 void *ifa_data; /* Address specific data */ 62.Ed 63.Pp 64The 65.Li ifa_next 66field contains a pointer to the next structure on the list. 67This field is 68.Dv NULL 69in last structure on the list. 70.Pp 71The 72.Li ifa_name 73field contains the interface name. 74.Pp 75The 76.Li ifa_flags 77field contains the interface flags, as set by 78.Xr ifconfig 8 79utility. 80.Pp 81The 82.Li ifa_addr 83field references either the address of the interface or the link level 84address of the interface, if one exists, otherwise it is NULL. 85(The 86.Li sa_family 87field of the 88.Li ifa_addr 89field should be consulted to determine the format of the 90.Li ifa_addr 91address.) 92.Pp 93The 94.Li ifa_netmask 95field references the netmask associated with 96.Li ifa_addr , 97if one is set, otherwise it is NULL. 98.Pp 99The 100.Li ifa_broadaddr 101field, 102which should only be referenced for non-P2P interfaces, 103references the broadcast address associated with 104.Li ifa_addr , 105if one exists, otherwise it is NULL. 106.Pp 107The 108.Li ifa_dstaddr 109field references the destination address on a P2P interface, 110if one exists, otherwise it is NULL. 111.Pp 112The 113.Li ifa_data 114field references address family specific data. For 115.Dv AF_LINK 116addresses it contains a pointer to the 117.Fa struct if_data 118(as defined in include file 119.In net/if.h ) 120which contains various interface attributes and statistics. 121For all other address families, it contains a pointer to the 122.Fa struct ifa_data 123(as defined in include file 124.In net/if.h ) 125which contains per-address interface statistics. 126.Pp 127The data returned by 128.Fn getifaddrs 129is dynamically allocated and should be freed using 130.Fn freeifaddrs 131when no longer needed. 132.Sh RETURN VALUES 133.Rv -std getifaddrs 134.Sh ERRORS 135The 136.Fn getifaddrs 137may fail and set 138.Va errno 139for any of the errors specified for the library routines 140.Xr ioctl 2 , 141.Xr socket 2 , 142.Xr malloc 3 143or 144.Xr sysctl 3 . 145.Sh SEE ALSO 146.Xr ioctl 2 , 147.Xr socket 2 , 148.Xr sysctl 3 , 149.Xr networking 4 , 150.Xr ifconfig 8 151.Sh HISTORY 152The 153.Nm 154implementation first appeared in BSDi 155.Bsx . 156.Sh BUGS 157If both 158.In net/if.h 159and 160.In ifaddrs.h 161are being included, 162.In net/if.h 163.Em must 164be included before 165.In ifaddrs.h . 166