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 in6_ndireq;
  53 struct lagg_reqall;
  54 struct lagg_reqflags;
  55 struct lagg_reqopts;
  56 struct lagg_reqport;
  57
  58 struct ifconfig_capabilities {
  59         /** Current capabilities (ifconfig prints this as 'options')*/
  60         int curcap;
  61         /** Requested capabilities (ifconfig prints this as 'capabilities')*/
  62         int reqcap;
  63 };
  64
  65 /** Stores extra info associated with an inet address */
  66 struct ifconfig_inet_addr {
  67         const struct sockaddr_in *sin;
  68         const struct sockaddr_in *netmask;
  69         const struct sockaddr_in *dst;
  70         const struct sockaddr_in *broadcast;
  71         int prefixlen;
  72         uint8_t vhid;
  73 };
  74
  75 /** Stores extra info associated with an inet6 address */
  76 struct ifconfig_inet6_addr {
  77         struct sockaddr_in6 *sin6;
  78         struct sockaddr_in6 *dstin6;
  79         struct in6_addrlifetime lifetime;
  80         int prefixlen;
  81         uint32_t flags;
  82         uint8_t vhid;
  83 };
  84
  85 /** Stores extra info associated with a lagg(4) interface */
  86 struct ifconfig_lagg_status {
  87         struct lagg_reqall *ra;
  88         struct lagg_reqopts *ro;
  89         struct lagg_reqflags *rf;
  90 };
  91
  92 /** Retrieves a new state object for use in other API calls.
  93  * Example usage:
  94  *{@code
  95  * // Create state object
  96  * ifconfig_handle_t *lifh;
  97  * lifh = ifconfig_open();
  98  * if (lifh == NULL) {
  99  *     // Handle error
 100  * }
 101  *
 102  * // Do stuff with the handle
 103  *
 104  * // Dispose of the state object
 105  * ifconfig_close(lifh);
 106  * lifh = NULL;
 107  *}
 108  */
 109 ifconfig_handle_t *ifconfig_open(void);
 110
 111 /** Frees resources held in the provided state object.
 112  * @param h The state object to close.
 113  * @see #ifconfig_open(void)
 114  */
 115 void ifconfig_close(ifconfig_handle_t *h);
 116
 117 /** Identifies what kind of error occured. */
 118 ifconfig_errtype ifconfig_err_errtype(ifconfig_handle_t *h);
 119
 120 /** Retrieves the errno associated with the error, if any. */
 121 int ifconfig_err_errno(ifconfig_handle_t *h);
 122
 123 typedef void (*ifconfig_foreach_func_t)(ifconfig_handle_t *h,
 124     struct ifaddrs *ifa, void *udata);
 125
 126 /** Iterate over every network interface
 127  * @param h     An open ifconfig state object
 128  * @param cb    A callback function to call with a pointer to each interface
 129  * @param udata An opaque value that will be passed to the callback.
 130  * @return      0 on success, nonzero if the list could not be iterated
 131  */
 132 int ifconfig_foreach_iface(ifconfig_handle_t *h, ifconfig_foreach_func_t cb,
 133     void *udata);
 134
 135 /** Iterate over every address on a single network interface
 136  * @param h     An open ifconfig state object
 137  * @param ifa   A pointer that was supplied by a previous call to
 138  *              ifconfig_foreach_iface
 139  * @param udata An opaque value that will be passed to the callback.
 140  * @param cb    A callback function to call with a pointer to each ifaddr
 141  */
 142 void ifconfig_foreach_ifaddr(ifconfig_handle_t *h, struct ifaddrs *ifa,
 143     ifconfig_foreach_func_t cb, void *udata);
 144
 145 /** If error type was IOCTL, this identifies which request failed. */
 146 unsigned long ifconfig_err_ioctlreq(ifconfig_handle_t *h);
 147 int ifconfig_get_description(ifconfig_handle_t *h, const char *name,
 148     char **description);
 149 int ifconfig_set_description(ifconfig_handle_t *h, const char *name,
 150     const char *newdescription);
 151 int ifconfig_unset_description(ifconfig_handle_t *h, const char *name);
 152 int ifconfig_set_name(ifconfig_handle_t *h, const char *name,
 153     const char *newname);
 154 int ifconfig_get_orig_name(ifconfig_handle_t *h, const char *ifname,
 155     char **orig_name);
 156 int ifconfig_set_fib(ifconfig_handle_t *h, const char *name, int fib);
 157 int ifconfig_get_fib(ifconfig_handle_t *h, const char *name, int *fib);
 158 int ifconfig_set_mtu(ifconfig_handle_t *h, const char *name, const int mtu);
 159 int ifconfig_get_mtu(ifconfig_handle_t *h, const char *name, int *mtu);
 160 int ifconfig_get_nd6(ifconfig_handle_t *h, const char *name,
 161     struct in6_ndireq *nd);
 162 int ifconfig_set_metric(ifconfig_handle_t *h, const char *name,
 163     const int metric);
 164 int ifconfig_get_metric(ifconfig_handle_t *h, const char *name, int *metric);
 165 int ifconfig_set_capability(ifconfig_handle_t *h, const char *name,
 166     const int capability);
 167 int ifconfig_get_capability(ifconfig_handle_t *h, const char *name,
 168     struct ifconfig_capabilities *capability);
 169
 170 /** Retrieve the list of groups to which this interface belongs
 171  * @param h     An open ifconfig state object
 172  * @param name  The interface name
 173  * @param ifgr  return argument.  The caller is responsible for freeing
 174  *              ifgr->ifgr_groups
 175  * @return      0 on success, nonzero on failure
 176  */
 177 int ifconfig_get_groups(ifconfig_handle_t *h, const char *name,
 178     struct ifgroupreq *ifgr);
 179 int ifconfig_get_ifstatus(ifconfig_handle_t *h, const char *name,
 180     struct ifstat *stat);
 181
 182 /** Retrieve the interface media information
 183  * @param h     An open ifconfig state object
 184  * @param name  The interface name
 185  * @param ifmr  Return argument.  The caller is responsible for freeing it
 186  * @return      0 on success, nonzero on failure
 187  */
 188 int ifconfig_media_get_mediareq(ifconfig_handle_t *h, const char *name,
 189     struct ifmediareq **ifmr);
 190 const char *ifconfig_media_get_type(int ifmw);
 191 const char *ifconfig_media_get_subtype(int ifmw);
 192 const char *ifconfig_media_get_status(const struct ifmediareq *ifmr);
 193 void ifconfig_media_get_options_string(int ifmw, char *buf, size_t buflen);
 194
 195 int ifconfig_carp_get_info(ifconfig_handle_t *h, const char *name,
 196     struct carpreq *carpr, int ncarpr);
 197
 198 /** Retrieve additional information about an inet address
 199  * @param h     An open ifconfig state object
 200  * @param name  The interface name
 201  * @param ifa   Pointer to the the address structure of interest
 202  * @param addr  Return argument.  It will be filled with additional information
 203  *              about the address.
 204  * @return      0 on success, nonzero on failure.
 205  */
 206 int ifconfig_inet_get_addrinfo(ifconfig_handle_t *h,
 207     const char *name, struct ifaddrs *ifa, struct ifconfig_inet_addr *addr);
 208
 209 /** Retrieve additional information about an inet6 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_inet6_get_addrinfo(ifconfig_handle_t *h,
 218     const char *name, struct ifaddrs *ifa, struct ifconfig_inet6_addr *addr);
 219
 220 /** Retrieve additional information about a lagg(4) interface */
 221 int ifconfig_lagg_get_lagg_status(ifconfig_handle_t *h,
 222     const char *name, struct ifconfig_lagg_status **lagg_status);
 223
 224 /** Retrieve additional information about a member of a lagg(4) interface */
 225 int ifconfig_lagg_get_laggport_status(ifconfig_handle_t *h,
 226     const char *name, struct lagg_reqport *rp);
 227
 228 /** Frees the structure returned by ifconfig_lagg_get_status.  Does nothing if
 229  * the argument is NULL
 230  * @param laggstat      Pointer to the structure to free
 231  */
 232 void ifconfig_lagg_free_lagg_status(struct ifconfig_lagg_status *laggstat);
 233
 234 /** Destroy a virtual interface
 235  * @param name Interface to destroy
 236  */
 237 int ifconfig_destroy_interface(ifconfig_handle_t *h, const char *name);
 238
 239 /** Creates a (virtual) interface
 240  * @param name Name of interface to create. Example: bridge or bridge42
 241  * @param name ifname Is set to actual name of created interface
 242  */
 243 int ifconfig_create_interface(ifconfig_handle_t *h, const char *name,
 244     char **ifname);
 245
 246 /** Creates a (virtual) interface
 247  * @param name Name of interface to create. Example: vlan0 or ix0.50
 248  * @param name ifname Is set to actual name of created interface
 249  * @param vlandev Name of interface to attach to
 250  * @param vlanid VLAN ID/Tag. Must not be 0.
 251  */
 252 int ifconfig_create_interface_vlan(ifconfig_handle_t *h, const char *name,
 253     char **ifname, const char *vlandev, const unsigned short vlantag);
 254
 255 int ifconfig_set_vlantag(ifconfig_handle_t *h, const char *name,
 256     const char *vlandev, const unsigned short vlantag);