xref: /dragonfly/lib/libc/net/getifaddrs.3 (revision 0cfebe3d) 
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