Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
$Id: isc_netif.3,v 1.5 2001/01/09 21:48:00 bwelling Exp $
.Dd Jun 30, 2000 .Dt ISC_NETIF 3 .Os BIND9 9 .Sh NAME .Nm isc_interfaceiter_create , .Nm internal_current ,
.Nm internal_next ,
.Nm internal_destroy ,
.Nm get_addr ,
.Nm isc_interfaceiter_current , .Nm isc_interfaceiter_first , .Nm isc_interfaceiter_next , .Nm isc_interfaceiter_destroy .Nd network interface management .Sh SYNOPSIS .Fd #include <config.h> .Fd #include <sys/types.h> .Fd #include <sys/ioctl.h> .Fd #ifdef HAVE_SYS_SOCKIO_H .Fd #include <sys/sockio.h> /* Required for ifiter_ioctl.c. */ .Fd #endif .Fd #include <stdio.h> .Fd #include <stdlib.h> .Fd #include <unistd.h> .Fd #include <errno.h> .Fd #include <isc/mem.h> .Fd #include <isc/net.h> .Fd #include <isc/result.h> .Fd #include <isc/string.h> .Fd #include <isc/types.h> .Fd #include <isc/interfaceiter.h> .Fd #include <isc/util.h> .Fd #include <net/if.h> /* Must follow <isc/net.h>. */ .Ft isc_result_t .Fo isc_interfaceiter_create .Fa "isc_mem_t *mctx" .Fa "isc_interfaceiter_t **iterp" .Fc .Ft static isc_result_t
.Fo internal_current
.Fc
.Ft static isc_result_t
.Fo internal_next
.Fc
.Ft static void
.Fo internal_destroy
.Fc
.Ft static void
.Fo get_addr
.Fa "unsigned int family"
.Fa "isc_netaddr_t *dst"
.Fa "struct sockaddr *src"
.Fc
.Ft isc_result_t .Fo isc_interfaceiter_current .Fa "isc_interfaceiter_t *iter" .Fa "isc_interface_t *ifdata" .Fc .Ft isc_result_t .Fo isc_interfaceiter_first .Fa "isc_interfaceiter_t *iter" .Fc .Ft isc_result_t .Fo isc_interfaceiter_next .Fa "isc_interfaceiter_t *iter" .Fc .Ft void .Fo isc_interfaceiter_destroy "isc_interfaceiter_t **iter" .Fc .Sh DESCRIPTION Details of the system's network interfaces can be retrieved with .Fn isc_interfaceiter_create . It uses .Xr sysctl 3 or an .Dv SIOCGLIFCONF .Xr ioctl 2 to get the information from the kernel. Configuration details of the system's network interfaces - IP addresses, network mask, status, MAC address, etc. - is stored in a buffer which is accessed through .Fa iterp . Memory is allocated from the memory context .Fa mctx to store this information. The maximum buffer size that can be used to store the configuration data of all the network interfaces is 1 Megabyte This data buffer should be far more than enough for a system with a sensible number of network interfaces.
p
The
.Dv isc_interfaceiter_t
structure is not accessed directly.
The contents of this structure are\p
operating system specific.
They depend on whether the kernel provides a
.Xr sysctl 3
or
.Dv SIOCGLIFCONF
.Xr ioctl 2
interface for retreiving network interface details.
Information from the
.Dv isc_interfaceiter_t
can be accessed using
.Fn isc_interfaceiter_current ,
.Fn isc_interfaceiter_first
and
.Fn isc_interfaceiter_next .
which use the internal functions
.Fa internal_current
and
.Fa internal_next .
.Pp
.Fn internal_current
gets information for the current network interface from
.Fa iter .
.Fn internal_current
sets
.Dv iter->current
to point at the information about the current interface.
.Fa internal_next
gets the next interface in the list created by
.Fn isc_interfaceiter_create .
Unlike
.Fn isc_interfaceiter_next ,
calls to
.Fn internal_next
can position the
.Fa iter
pointers at an interface which will be ignored because it uses an
unsupported address family: a non-IP interface for example.
.Pp
.Fn internal_destroy
does nothing.
It serves as a stub for
.Xr isc_interfaceiter_destroy 3 .
.Pp
.Fn get_addr
extracts the network address part of the
.Dv sockaddr
struct referenced by
.Fa src
and copies it to
.Fa dst .
.Fa family
indicates the address family \*-
.Dv AF_INET
or
.Dv AF_INET6 .
The address family is given explicitly because the network address might
contain a netmask obtained by an
.Dv SIOCGIFNETMASK
.Xr ioctl 2 .
which will not assign a valid address family to
.Dv src->sa_family .
p .Fn isc_interfaceiter_current copies the configuration details of .Fa iter 's current network interface to .Fa ifdata .
p .Fn isc_interfaceiter_first locates the first network interface in .Fa iter which has an address in a supported address family: i.e. an IPv4 or IPv6 address. .Fn isc_interfaceiter_next find the next network interface in the list referenced by .Fa iter that has an IPv4 or IPv6 address.
p
The
.Dv isc_interfaceiter_t
structure referenced by
.Fa iterp
is discarded by calling
.Fn isc_interfaceiter_destroy .
Any memory associated with
.Fa iterp is freed.
.Sh RETURN VALUES
Successful calls to
.Fn isc_interfaceiter_create
return
.Er ISC_R_SUCCESS .
The function returns
.Er ISC_R_NOMEMORY
if it was unable to allocate enough memory for the list if network
interfaces.
.Er ISC_R_UNEXPECTED
is returned and an error message printed on
.Dv stderr
if it was not possible to obtain a list of network interfaces.
.Pp
.Fa internal_current
returns
.Er ISC_R_SUCCESS
on success.
If the current interface uses an unsupported address family or if some
operation on the interface fails, the function returns
.Er ISC_R_IGNORE .
.Pp
.Er ISC_R_NOMORE
is returned by
.Fn internal_next
when there are no more entries in the list of interfaces referenced
via
.Fa iter.
It returns
.Er ISC_R_SUCCESS
otherwise.
p .Fn isc_interfaceiter_current always returns .Er ISC_R_SUCCESS if .Fa iter points to a valid .Dv isc_interfaceiter_t structure.
p .Fn isc_interfaceiter_first and .Fn isc_interfaceiter_next return .Er ISC_R_SUCCESS on success or .Er ISC_R_NOMORE if there are no more network interfaces in .Fa iter . .Sh SEE ALSO .Xr netintro 4, .Xr sysctl 3 , .Xr ioctl 2 , .Xr ifconfig 8 .