mirror of
https://github.com/isc-projects/bind9.git
synced 2026-05-04 17:24:47 -04:00
258 lines
6.6 KiB
Groff
258 lines
6.6 KiB
Groff
.\" Copyright (C) 2000 Internet Software Consortium.
|
|
.\"
|
|
.\" 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.2 2000/07/27 09:43:11 tale Exp $
|
|
.\"
|
|
.Dd Jun 30, 2000
|
|
.Dt ISC_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
|
|
.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.
|
|
.Pp
|
|
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 .
|
|
.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 the list referenced by
|
|
.Fa iter
|
|
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 ifconfig 8 .
|