1 '\" t 2 .\" 3 .\" This file and its contents are supplied under the terms of the 4 .\" Common Development and Distribution License ("CDDL"), version 1.0. 5 .\" You may only use this file in accordance with the terms of version 6 .\" 1.0 of the CDDL. 7 .\" 8 .\" A full copy of the text of the CDDL should have accompanied this 9 .\" source. A copy of the CDDL is also available via the Internet at 10 .\" http://www.illumos.org/license/CDDL. 11 .\" 12 .\" 13 .\" Copyright (c) 2013, Joyent, Inc. All rights reserved. 14 .\" 15 .TH GETIFADDRS 3SOCKET "Apr 18, 2013" 16 .SH NAME 17 getifaddrs, freeifaddrs \- get interface addresses 18 .SH SYNOPSIS 19 .LP 20 .nf 21 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB-lnsl\fR \ 22 [ \fIlibrary\fR ... ] 23 #include <sys/types.h> 24 #include <sys/socket.h> 25 #include <ifaddrs.h> 26 .fi 27 28 .LP 29 .nf 30 \fBint\fR \fBgetifaddrs\fR(\fBstruct ifaddrs **\fR\fIifap\fR); 31 .fi 32 33 .LP 34 .nf 35 \fBvoid\fR \fBfreeifaddrs\fR(\fBstruct ifaddrs *\fR\fIifp\fR); 36 .fi 37 38 .SH DESCRIPTION 39 .sp 40 .LP 41 The \fBgetifaddrs\fR() function is used to obtain the list of network 42 interfaces on the local machine. A reference to a linked list of \fBifaddrs\fR 43 structures, as defined in \fB<ifaddrs.h>\fR, is stored in the memory referenced 44 by \fIifap\fR. Each structure in the list describes one network interface 45 address, and is of the form: 46 47 .sp 48 .in +2 49 .nf 50 struct ifaddrs { 51 struct ifaddrs *ifa_next; 52 char *ifa_name; 53 uint64_t ifa_flags; 54 struct sockaddr *ifa_addr; 55 struct sockaddr *ifa_netmask; 56 union { 57 struct sockaddr *ifu_broadaddr; 58 struct sockaddr *ifu_dstaddr; 59 } ifa_ifu; 60 void *ifa_data; 61 }; 62 #define ifa_broadaddr ifa_ifu.ifu_broadaddr 63 #define ifa_dstaddr ifa_ifu.ifu_dstaddr 64 .fi 65 .in -2 66 67 .sp 68 .LP 69 The list is traversed by following the \fIifa_next\fR pointer. This member is 70 \fBNULL\fR on the last structure in the list. 71 72 .sp 73 .LP 74 The \fIifa_name\fR member contains the interface name. 75 76 .sp 77 .LP 78 The \fIifa_flags\fR member contains the interface flags. 79 80 .sp 81 .LP 82 The \fIifa_addr\fR member references the address of the interface. Use the 83 \fIsa_family\fR member of this structure to determine the format of the 84 address, as described in \fBsocket.h\fR(3HEAD). 85 86 .sp 87 .LP 88 The \fIifa_netmask\fR member references the netmask associated with ifa_addr, 89 or \fBNULL\fR if one is not set. 90 91 .sp 92 .LP 93 If the \fBIFF_BROADCAST\fR bit is set in \fIifa_flags\fR, then 94 \fIifa_broadaddr\fR is valid, or \fBNULL\fR if not present. If the 95 \fBIFF_POINTOPOINT\fR bit is set, then \fifa_dstaddr\fR is valid, or \fBNULL\fR 96 if not present. These two flags are mutually exclusive; see \fBif_tcp\fR(7P) 97 for more information. 98 99 .sp 100 .LP 101 The \fIifa_data\fR member is presently unused. 102 103 .sp 104 .LP 105 The memory used by \fBgetifaddrs\fR() to back the list is dynamically allocated. 106 It should be freed using \fBfreeifaddrs\fR(). 107 108 .SH RETURN VALUES 109 .sp 110 .LP 111 If successful, \fBgetifaddrs\fR() returns the value \fB0\fR; otherwise it 112 returns \fB\(mi1\fR and sets \fIerrno\fR to indicate the error. 113 114 .SH ERRORS 115 .sp 116 .LP 117 The \fBgetifaddrs\fR() function may fail and set \fIerrno\fR for any of the 118 errors specified for the library routines \fBioctl\fR(2), 119 \fBsocket\fR(3SOCKET), and \fBmalloc\fR(3C). 120 121 .SH ATTRIBUTES 122 .sp 123 .TS 124 box; 125 c | c 126 l | l . 127 ATTRIBUTE TYPE ATTRIBUTE VALUE 128 _ 129 Interface Stability Committed 130 _ 131 MT-Level MT-Safe 132 .TE 133 134 .SH SEE ALSO 135 .sp 136 .LP 137 \fBipadm\fR(1M), \fBifconfig\fR(1M), \fBioctl\fR(2), \fBmalloc\fR(3C), 138 \fBsocket\fR(3SOCKET), \fBsocket.h\fR(3HEAD), \fBif_tcp\fR(7P), 139 \fBattributes\fR(5) 140 141 .SH NOTES 142 .sp 143 .LP 144 On an illumos system, this function lists only interfaces with the \fBIFF_UP\fR 145 flag set; see \fBif_tcp\fR(7P) and \fBifconfig\fR(1M) for more information. 146 147 .SH BUGS 148 .sp 149 .LP 150 At present, this function only lists addresses from the \fBAF_INET\fR and 151 \fBAF_INET6\fR families. Other families, such as \fBAF_LINK\fR, are not 152 included.