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: netif.man,v 1.2 2000/06/22 00:52:12 tale Exp $
.Dd Jun 30, 2000 .Dt 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 .Fn isc_interfaceiter_create "isc_mem_t *mctx" "isc_interfaceiter_t **iterp" .Ft static isc_result_t .Fn internal_current .Ft static isc_result_t .Fn internal_next .Ft static void .Fn internal_destroy .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 .Fn isc_interfaceiter_first "isc_interfaceiter_t *iter" .Ft isc_result_t .Fn isc_interfaceiter_next "isc_interfaceiter_t *iter" .Ft void .Fn isc_interfaceiter_destroy "isc_interfaceiter_t **iter" .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. The .Dv isc_interfaceiter_t structure is not accessed directly. Information is\p obtained using .Fa isc_interfaceiter_current , .Fa isc_interfaceiter_first and .Fa isc_interfaceiter_next which use the internal functions .Fa internal_current and .Fa internal_next .
p .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.
p .Fn internal_destroy does nothing. It serves as a stub for .Xr isc_interfaceiter_destroy 3 .
p .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 .Fa iter 's list 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.
p .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 .
p .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 isc_interfaceiter_current 3 , .Xr isc_interfaceiter_first 3 , .Xr isc_interfaceiter_next 3 , .Xr isc_interfaceiter_destroy 3 , .Xr ifconfig 8 .