lib/libifconfig/libifconfig.h

   1 /*
   2  * Copyright (c) 2016-2017, Marie Helene Kvello-Aune
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without modification,
   6  * are permitted provided that the following conditions are met:
   7  *
   8  * 1. Redistributions of source code must retain the above copyright notice,
   9  * thislist of conditions and the following disclaimer.
  10  *
  11  * 2. Redistributions in binary form must reproduce the above copyright notice,
  12  * this list of conditions and the following disclaimer in the documentation and/or
  13  * other materials provided with the distribution.
  14  *
  15  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  16  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  17  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
  19  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  21  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  22  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  23  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  24  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25  *
  26  * $FreeBSD$
  27  */
  28
  29 #pragma once
  30
  31 #include <netinet/in.h>
  32 #include <netinet6/in6_var.h>
  33
  34 #define ND6_IFF_DEFAULTIF    0x8000
  35
  36 typedef enum {
  37         OK = 0,
  38         OTHER,
  39         IOCTL,
  40         SOCKET
  41 } ifconfig_errtype;
  42
  43 /*
  44  * Opaque definition so calling application can just pass a
  45  * pointer to it for library use.
  46  */
  47 struct ifconfig_handle;
  48 typedef struct ifconfig_handle ifconfig_handle_t;
  49
  50 struct carpreq;
  51 struct ifaddrs;
  52 struct ifbropreq;
  53 struct ifbreq;
  54 struct in6_ndireq;
  55 struct lagg_reqall;
  56 struct lagg_reqflags;
  57 struct lagg_reqopts;
  58 struct lagg_reqport;
  59
  60 /** Stores extra info associated with a bridge(4) interface */
  61 struct ifconfig_bridge_status {
  62         struct ifbropreq *params;       /**< current operational parameters */
  63         struct ifbreq *members;         /**< list of bridge members */
  64         size_t members_count;           /**< how many member interfaces */
  65         uint32_t cache_size;            /**< size of address cache */
  66         uint32_t cache_lifetime;        /**< address cache entry lifetime */
  67 };
  68
  69 struct ifconfig_capabilities {
  70         /** Current capabilities (ifconfig prints this as 'options')*/
  71         int curcap;
  72         /** Requested capabilities (ifconfig prints this as 'capabilities')*/
  73         int reqcap;
  74 };
  75
  76 /** Stores extra info associated with an inet address */
  77 struct ifconfig_inet_addr {
  78         const struct sockaddr_in *sin;
  79         const struct sockaddr_in *netmask;
  80         const struct sockaddr_in *dst;
  81         const struct sockaddr_in *broadcast;
  82         int prefixlen;
  83         uint8_t vhid;
  84 };
  85
  86 /** Stores extra info associated with an inet6 address */
  87 struct ifconfig_inet6_addr {
  88         struct sockaddr_in6 *sin6;
  89         struct sockaddr_in6 *dstin6;
  90         struct in6_addrlifetime lifetime;
  91         int prefixlen;
  92         uint32_t flags;
  93         uint8_t vhid;
  94 };
  95
  96 /** Stores extra info associated with a lagg(4) interface */
  97 struct ifconfig_lagg_status {
  98         struct lagg_reqall *ra;
  99         struct lagg_reqopts *ro;
 100         struct lagg_reqflags *rf;
 101 };
 102
 103 /** Retrieves a new state object for use in other API calls.
 104  * Example usage:
 105  *{@code
 106  * // Create state object
 107  * ifconfig_handle_t *lifh;
 108  * lifh = ifconfig_open();
 109  * if (lifh == NULL) {
 110  *     // Handle error
 111  * }
 112  *
 113  * // Do stuff with the handle
 114  *
 115  * // Dispose of the state object
 116  * ifconfig_close(lifh);
 117  * lifh = NULL;
 118  *}
 119  */
 120 ifconfig_handle_t *ifconfig_open(void);
 121
 122 /** Frees resources held in the provided state object.
 123  * @param h The state object to close.
 124  * @see #ifconfig_open(void)
 125  */
 126 void ifconfig_close(ifconfig_handle_t *h);
 127
 128 /** Identifies what kind of error occured. */
 129 ifconfig_errtype ifconfig_err_errtype(ifconfig_handle_t *h);
 130
 131 /** Retrieves the errno associated with the error, if any. */
 132 int ifconfig_err_errno(ifconfig_handle_t *h);
 133
 134 typedef void (*ifconfig_foreach_func_t)(ifconfig_handle_t *h,
 135     struct ifaddrs *ifa, void *udata);
 136
 137 /** Iterate over every network interface
 138  * @param h     An open ifconfig state object
 139  * @param cb    A callback function to call with a pointer to each interface
 140  * @param udata An opaque value that will be passed to the callback.
 141  * @return      0 on success, nonzero if the list could not be iterated
 142  */
 143 int ifconfig_foreach_iface(ifconfig_handle_t *h, ifconfig_foreach_func_t cb,
 144     void *udata);
 145
 146 /** Iterate over every address on a single network interface
 147  * @param h     An open ifconfig state object
 148  * @param ifa   A pointer that was supplied by a previous call to
 149  *              ifconfig_foreach_iface
 150  * @param udata An opaque value that will be passed to the callback.
 151  * @param cb    A callback function to call with a pointer to each ifaddr
 152  */
 153 void ifconfig_foreach_ifaddr(ifconfig_handle_t *h, struct ifaddrs *ifa,
 154     ifconfig_foreach_func_t cb, void *udata);
 155
 156 /** If error type was IOCTL, this identifies which request failed. */
 157 unsigned long ifconfig_err_ioctlreq(ifconfig_handle_t *h);
 158 int ifconfig_get_description(ifconfig_handle_t *h, const char *name,
 159     char **description);
 160 int ifconfig_set_description(ifconfig_handle_t *h, const char *name,
 161     const char *newdescription);
 162 int ifconfig_unset_description(ifconfig_handle_t *h, const char *name);
 163 int ifconfig_set_name(ifconfig_handle_t *h, const char *name,
 164     const char *newname);
 165 int ifconfig_get_orig_name(ifconfig_handle_t *h, const char *ifname,
 166     char **orig_name);
 167 int ifconfig_set_fib(ifconfig_handle_t *h, const char *name, int fib);
 168 int ifconfig_get_fib(ifconfig_handle_t *h, const char *name, int *fib);
 169 int ifconfig_set_mtu(ifconfig_handle_t *h, const char *name, const int mtu);
 170 int ifconfig_get_mtu(ifconfig_handle_t *h, const char *name, int *mtu);
 171 int ifconfig_get_nd6(ifconfig_handle_t *h, const char *name,
 172     struct in6_ndireq *nd);
 173 int ifconfig_set_metric(ifconfig_handle_t *h, const char *name,
 174     const int metric);
 175 int ifconfig_get_metric(ifconfig_handle_t *h, const char *name, int *metric);
 176 int ifconfig_set_capability(ifconfig_handle_t *h, const char *name,
 177     const int capability);
 178 int ifconfig_get_capability(ifconfig_handle_t *h, const char *name,
 179     struct ifconfig_capabilities *capability);
 180
 181 /** Retrieve the list of groups to which this interface belongs
 182  * @param h     An open ifconfig state object
 183  * @param name  The interface name
 184  * @param ifgr  return argument.  The caller is responsible for freeing
 185  *              ifgr->ifgr_groups
 186  * @return      0 on success, nonzero on failure
 187  */
 188 int ifconfig_get_groups(ifconfig_handle_t *h, const char *name,
 189     struct ifgroupreq *ifgr);
 190 int ifconfig_get_ifstatus(ifconfig_handle_t *h, const char *name,
 191     struct ifstat *stat);
 192
 193 /** Retrieve the interface media information
 194  * @param h     An open ifconfig state object
 195  * @param name  The interface name
 196  * @param ifmr  Return argument.  The caller is responsible for freeing it
 197  * @return      0 on success, nonzero on failure
 198  */
 199 int ifconfig_media_get_mediareq(ifconfig_handle_t *h, const char *name,
 200     struct ifmediareq **ifmr);
 201 const char *ifconfig_media_get_type(int ifmw);
 202 const char *ifconfig_media_get_subtype(int ifmw);
 203 const char *ifconfig_media_get_status(const struct ifmediareq *ifmr);
 204 void ifconfig_media_get_options_string(int ifmw, char *buf, size_t buflen);
 205
 206 int ifconfig_carp_get_info(ifconfig_handle_t *h, const char *name,
 207     struct carpreq *carpr, int ncarpr);
 208
 209 /** Retrieve additional information about an inet address
 210  * @param h     An open ifconfig state object
 211  * @param name  The interface name
 212  * @param ifa   Pointer to the the address structure of interest
 213  * @param addr  Return argument.  It will be filled with additional information
 214  *              about the address.
 215  * @return      0 on success, nonzero on failure.
 216  */
 217 int ifconfig_inet_get_addrinfo(ifconfig_handle_t *h,
 218     const char *name, struct ifaddrs *ifa, struct ifconfig_inet_addr *addr);
 219
 220 /** Retrieve additional information about an inet6 address
 221  * @param h     An open ifconfig state object
 222  * @param name  The interface name
 223  * @param ifa   Pointer to the the address structure of interest
 224  * @param addr  Return argument.  It will be filled with additional information
 225  *              about the address.
 226  * @return      0 on success, nonzero on failure.
 227  */
 228 int ifconfig_inet6_get_addrinfo(ifconfig_handle_t *h,
 229     const char *name, struct ifaddrs *ifa, struct ifconfig_inet6_addr *addr);
 230
 231 /** Retrieve additional information about a bridge(4) interface */
 232 int ifconfig_bridge_get_bridge_status(ifconfig_handle_t *h,
 233     const char *name, struct ifconfig_bridge_status **bridge);
 234
 235 /** Frees the structure returned by ifconfig_bridge_get_bridge_status.  Does
 236  * nothing if the argument is NULL
 237  * @param bridge        Pointer to the structure to free
 238  */
 239 void ifconfig_bridge_free_bridge_status(struct ifconfig_bridge_status *bridge);
 240
 241 /** Retrieve additional information about a lagg(4) interface */
 242 int ifconfig_lagg_get_lagg_status(ifconfig_handle_t *h,
 243     const char *name, struct ifconfig_lagg_status **lagg_status);
 244
 245 /** Retrieve additional information about a member of a lagg(4) interface */
 246 int ifconfig_lagg_get_laggport_status(ifconfig_handle_t *h,
 247     const char *name, struct lagg_reqport *rp);
 248
 249 /** Frees the structure returned by ifconfig_lagg_get_lagg_status.  Does
 250  * nothing if the argument is NULL
 251  * @param laggstat      Pointer to the structure to free
 252  */
 253 void ifconfig_lagg_free_lagg_status(struct ifconfig_lagg_status *laggstat);
 254
 255 /** Destroy a virtual interface
 256  * @param name Interface to destroy
 257  */
 258 int ifconfig_destroy_interface(ifconfig_handle_t *h, const char *name);
 259
 260 /** Creates a (virtual) interface
 261  * @param name Name of interface to create. Example: bridge or bridge42
 262  * @param name ifname Is set to actual name of created interface
 263  */
 264 int ifconfig_create_interface(ifconfig_handle_t *h, const char *name,
 265     char **ifname);
 266
 267 /** Creates a (virtual) interface
 268  * @param name Name of interface to create. Example: vlan0 or ix0.50
 269  * @param name ifname Is set to actual name of created interface
 270  * @param vlandev Name of interface to attach to
 271  * @param vlanid VLAN ID/Tag. Must not be 0.
 272  */
 273 int ifconfig_create_interface_vlan(ifconfig_handle_t *h, const char *name,
 274     char **ifname, const char *vlandev, const unsigned short vlantag);
 275
 276 int ifconfig_set_vlantag(ifconfig_handle_t *h, const char *name,
 277     const char *vlandev, const unsigned short vlantag);