git.saurik.com Git - apple/libinfo.git/blame_incremental

... / ...

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