bind9/doc/man/netif.man

.\"
.\" Copyright (C) 2000  Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this document 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.1 2000/06/01 03:19:06 jim Exp $
.\"
.Dd Jun 30, 2000
.Dt NETIF 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.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 .
.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 .
.Pp
.Fn isc_interfaceiter_current
copies the configuration details of 
.Fa iter 's
current network interface to
.Fa ifdata .
.Pp
.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.
.Pp
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.
.Pp
.Fn isc_interfaceiter_current
always returns
.Er ISC_R_SUCCESS
if 
.Fa iter
points to a valid 
.Dv isc_interfaceiter_t
structure.
.Pp
.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 .