1 /* $NetBSD: interfaceiter.h,v 1.1 2024/02/18 20:57:53 christos Exp $ */ 2 3 /* 4 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5 * 6 * SPDX-License-Identifier: MPL-2.0 7 * 8 * This Source Code Form is subject to the terms of the Mozilla Public 9 * License, v. 2.0. If a copy of the MPL was not distributed with this 10 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 11 * 12 * See the COPYRIGHT file distributed with this work for additional 13 * information regarding copyright ownership. 14 */ 15 16 #ifndef ISC_INTERFACEITER_H 17 #define ISC_INTERFACEITER_H 1 18 19 /***** 20 ***** Module Info 21 *****/ 22 23 /*! \file isc/interfaceiter.h 24 * \brief Iterates over the list of network interfaces. 25 * 26 * Interfaces whose address family is not supported are ignored and never 27 * returned by the iterator. Interfaces whose netmask, interface flags, 28 * or similar cannot be obtained are also ignored, and the failure is logged. 29 * 30 * Standards: 31 * The API for scanning varies greatly among operating systems. 32 * This module attempts to hide the differences. 33 */ 34 35 /*** 36 *** Imports 37 ***/ 38 39 #include <inttypes.h> 40 41 #include <isc/lang.h> 42 #include <isc/netaddr.h> 43 #include <isc/types.h> 44 45 /*! 46 * \brief Public structure describing a network interface. 47 */ 48 49 struct isc_interface { 50 char name[32]; /*%< Interface name, null-terminated. */ 51 unsigned int af; /*%< Address family. */ 52 isc_netaddr_t address; /*%< Local address. */ 53 isc_netaddr_t netmask; /*%< Network mask. */ 54 isc_netaddr_t dstaddress; /*%< Destination address 55 * (point-to-point 56 * only). */ 57 uint32_t flags; /*%< Flags; see INTERFACE flags. */ 58 }; 59 60 /*@{*/ 61 /*! Interface flags. */ 62 63 #define INTERFACE_F_UP 0x00000001U 64 #define INTERFACE_F_POINTTOPOINT 0x00000002U 65 #define INTERFACE_F_LOOPBACK 0x00000004U 66 /*@}*/ 67 68 /*** 69 *** Functions 70 ***/ 71 72 ISC_LANG_BEGINDECLS 73 74 isc_result_t 75 isc_interfaceiter_create(isc_mem_t *mctx, isc_interfaceiter_t **iterp); 76 /*!< 77 * \brief Create an iterator for traversing the operating system's list 78 * of network interfaces. 79 * 80 * Returns: 81 *\li #ISC_R_SUCCESS 82 * \li #ISC_R_NOMEMORY 83 *\li Various network-related errors 84 */ 85 86 isc_result_t 87 isc_interfaceiter_first(isc_interfaceiter_t *iter); 88 /*!< 89 * \brief Position the iterator on the first interface. 90 * 91 * Returns: 92 *\li #ISC_R_SUCCESS Success. 93 *\li #ISC_R_NOMORE There are no interfaces. 94 */ 95 96 isc_result_t 97 isc_interfaceiter_current(isc_interfaceiter_t *iter, isc_interface_t *ifdata); 98 /*!< 99 * \brief Get information about the interface the iterator is currently 100 * positioned at and store it at *ifdata. 101 * 102 * Requires: 103 *\li The iterator has been successfully positioned using 104 * isc_interface_iter_first() / isc_interface_iter_next(). 105 * 106 * Returns: 107 *\li #ISC_R_SUCCESS Success. 108 */ 109 110 isc_result_t 111 isc_interfaceiter_next(isc_interfaceiter_t *iter); 112 /*!< 113 * \brief Position the iterator on the next interface. 114 * 115 * Requires: 116 * \li The iterator has been successfully positioned using 117 * isc_interface_iter_first() / isc_interface_iter_next(). 118 * 119 * Returns: 120 *\li #ISC_R_SUCCESS Success. 121 *\li #ISC_R_NOMORE There are no more interfaces. 122 */ 123 124 void 125 isc_interfaceiter_destroy(isc_interfaceiter_t **iterp); 126 /*!< 127 * \brief Destroy the iterator. 128 */ 129 130 ISC_LANG_ENDDECLS 131 132 #endif /* ISC_INTERFACEITER_H */ 133