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 <sys/types.h>
  32
  33 #include <net/if.h>
  34
  35 #include <netinet/in.h>
  36 #include <netinet6/in6_var.h>
  37
  38 #define ND6_IFF_DEFAULTIF    0x8000
  39
  40 typedef enum {
  41         OK = 0,
  42         OTHER,
  43         IOCTL,
  44         SOCKET
  45 } ifconfig_errtype;
  46
  47 /*
  48  * Opaque definition so calling application can just pass a
  49  * pointer to it for library use.
  50  */
  51 struct ifconfig_handle;
  52 typedef struct ifconfig_handle ifconfig_handle_t;
  53
  54 struct carpreq;
  55 struct ifaddrs;
  56 struct ifbropreq;
  57 struct ifbreq;
  58 struct in6_ndireq;
  59 struct lagg_reqall;
  60 struct lagg_reqflags;
  61 struct lagg_reqopts;
  62 struct lagg_reqport;
  63
  64 /** Stores extra info associated with a bridge(4) interface */
  65 struct ifconfig_bridge_status {
  66         struct ifbropreq *params;       /**< current operational parameters */
  67         struct ifbreq *members;         /**< list of bridge members */
  68         size_t members_count;           /**< how many member interfaces */
  69         uint32_t cache_size;            /**< size of address cache */
  70         uint32_t cache_lifetime;        /**< address cache entry lifetime */
  71 };
  72
  73 struct ifconfig_capabilities {
  74         /** Current capabilities (ifconfig prints this as 'options')*/
  75         int curcap;
  76         /** Requested capabilities (ifconfig prints this as 'capabilities')*/
  77         int reqcap;
  78 };
  79
  80 /** Stores extra info associated with an inet address */
  81 struct ifconfig_inet_addr {
  82         const struct sockaddr_in *sin;
  83         const struct sockaddr_in *netmask;
  84         const struct sockaddr_in *dst;
  85         const struct sockaddr_in *broadcast;
  86         int prefixlen;
  87         uint8_t vhid;
  88 };
  89
  90 /** Stores extra info associated with an inet6 address */
  91 struct ifconfig_inet6_addr {
  92         struct sockaddr_in6 *sin6;
  93         struct sockaddr_in6 *dstin6;
  94         struct in6_addrlifetime lifetime;
  95         int prefixlen;
  96         uint32_t flags;
  97         uint8_t vhid;
  98 };
  99
 100 /** Stores extra info associated with a lagg(4) interface */
 101 struct ifconfig_lagg_status {
 102         struct lagg_reqall *ra;
 103         struct lagg_reqopts *ro;
 104         struct lagg_reqflags *rf;
 105 };
 106
 107 /** Retrieves a new state object for use in other API calls.
 108  * Example usage:
 109  *{@code
 110  * // Create state object
 111  * ifconfig_handle_t *lifh;
 112  * lifh = ifconfig_open();
 113  * if (lifh == NULL) {
 114  *     // Handle error
 115  * }
 116  *
 117  * // Do stuff with the handle
 118  *
 119  * // Dispose of the state object
 120  * ifconfig_close(lifh);
 121  * lifh = NULL;
 122  *}
 123  */
 124 ifconfig_handle_t *ifconfig_open(void);
 125
 126 /** Frees resources held in the provided state object.
 127  * @param h The state object to close.
 128  * @see #ifconfig_open(void)
 129  */
 130 void ifconfig_close(ifconfig_handle_t *h);
 131
 132 /** Identifies what kind of error occured. */
 133 ifconfig_errtype ifconfig_err_errtype(ifconfig_handle_t *h);
 134
 135 /** Retrieves the errno associated with the error, if any. */
 136 int ifconfig_err_errno(ifconfig_handle_t *h);
 137
 138 typedef void (*ifconfig_foreach_func_t)(ifconfig_handle_t *h,
 139     struct ifaddrs *ifa, void *udata);
 140
 141 /** Iterate over every network interface
 142  * @param h     An open ifconfig state object
 143  * @param cb    A callback function to call with a pointer to each interface
 144  * @param udata An opaque value that will be passed to the callback.
 145  * @return      0 on success, nonzero if the list could not be iterated
 146  */
 147 int ifconfig_foreach_iface(ifconfig_handle_t *h, ifconfig_foreach_func_t cb,
 148     void *udata);
 149
 150 /** Iterate over every address on a single network interface
 151  * @param h     An open ifconfig state object
 152  * @param ifa   A pointer that was supplied by a previous call to
 153  *              ifconfig_foreach_iface
 154  * @param udata An opaque value that will be passed to the callback.
 155  * @param cb    A callback function to call with a pointer to each ifaddr
 156  */
 157 void ifconfig_foreach_ifaddr(ifconfig_handle_t *h, struct ifaddrs *ifa,
 158     ifconfig_foreach_func_t cb, void *udata);
 159
 160 /** If error type was IOCTL, this identifies which request failed. */
 161 unsigned long ifconfig_err_ioctlreq(ifconfig_handle_t *h);
 162 int ifconfig_get_description(ifconfig_handle_t *h, const char *name,
 163     char **description);
 164 int ifconfig_set_description(ifconfig_handle_t *h, const char *name,
 165     const char *newdescription);
 166 int ifconfig_unset_description(ifconfig_handle_t *h, const char *name);
 167 int ifconfig_set_name(ifconfig_handle_t *h, const char *name,
 168     const char *newname);
 169 int ifconfig_get_orig_name(ifconfig_handle_t *h, const char *ifname,
 170     char **orig_name);
 171 int ifconfig_set_fib(ifconfig_handle_t *h, const char *name, int fib);
 172 int ifconfig_get_fib(ifconfig_handle_t *h, const char *name, int *fib);
 173 int ifconfig_set_mtu(ifconfig_handle_t *h, const char *name, const int mtu);
 174 int ifconfig_get_mtu(ifconfig_handle_t *h, const char *name, int *mtu);
 175 int ifconfig_get_nd6(ifconfig_handle_t *h, const char *name,
 176     struct in6_ndireq *nd);
 177 int ifconfig_set_metric(ifconfig_handle_t *h, const char *name,
 178     const int metric);
 179 int ifconfig_get_metric(ifconfig_handle_t *h, const char *name, int *metric);
 180 int ifconfig_set_capability(ifconfig_handle_t *h, const char *name,
 181     const int capability);
 182 int ifconfig_get_capability(ifconfig_handle_t *h, const char *name,
 183     struct ifconfig_capabilities *capability);
 184
 185 /** Retrieve the list of groups to which this interface belongs
 186  * @param h     An open ifconfig state object
 187  * @param name  The interface name
 188  * @param ifgr  return argument.  The caller is responsible for freeing
 189  *              ifgr->ifgr_groups
 190  * @return      0 on success, nonzero on failure
 191  */
 192 int ifconfig_get_groups(ifconfig_handle_t *h, const char *name,
 193     struct ifgroupreq *ifgr);
 194 int ifconfig_get_ifstatus(ifconfig_handle_t *h, const char *name,
 195     struct ifstat *stat);
 196
 197 /** Retrieve the interface media information
 198  * @param h     An open ifconfig state object
 199  * @param name  The interface name
 200  * @param ifmr  Return argument.  The caller is responsible for freeing it
 201  * @return      0 on success, nonzero on failure
 202  */
 203 int ifconfig_media_get_mediareq(ifconfig_handle_t *h, const char *name,
 204     struct ifmediareq **ifmr);
 205 const char *ifconfig_media_get_type(int ifmw);
 206 const char *ifconfig_media_get_subtype(int ifmw);
 207 const char *ifconfig_media_get_status(const struct ifmediareq *ifmr);
 208 void ifconfig_media_get_options_string(int ifmw, char *buf, size_t buflen);
 209
 210 int ifconfig_carp_get_info(ifconfig_handle_t *h, const char *name,
 211     struct carpreq *carpr, int ncarpr);
 212
 213 /** Retrieve additional information about an inet address
 214  * @param h     An open ifconfig state object
 215  * @param name  The interface name
 216  * @param ifa   Pointer to the the address structure of interest
 217  * @param addr  Return argument.  It will be filled with additional information
 218  *              about the address.
 219  * @return      0 on success, nonzero on failure.
 220  */
 221 int ifconfig_inet_get_addrinfo(ifconfig_handle_t *h,
 222     const char *name, struct ifaddrs *ifa, struct ifconfig_inet_addr *addr);
 223
 224 /** Retrieve additional information about an inet6 address
 225  * @param h     An open ifconfig state object
 226  * @param name  The interface name
 227  * @param ifa   Pointer to the the address structure of interest
 228  * @param addr  Return argument.  It will be filled with additional information
 229  *              about the address.
 230  * @return      0 on success, nonzero on failure.
 231  */
 232 int ifconfig_inet6_get_addrinfo(ifconfig_handle_t *h,
 233     const char *name, struct ifaddrs *ifa, struct ifconfig_inet6_addr *addr);
 234
 235 /** Retrieve additional information about a bridge(4) interface */
 236 int ifconfig_bridge_get_bridge_status(ifconfig_handle_t *h,
 237     const char *name, struct ifconfig_bridge_status **bridge);
 238
 239 /** Frees the structure returned by ifconfig_bridge_get_bridge_status.  Does
 240  * nothing if the argument is NULL
 241  * @param bridge        Pointer to the structure to free
 242  */
 243 void ifconfig_bridge_free_bridge_status(struct ifconfig_bridge_status *bridge);
 244
 245 /** Retrieve additional information about a lagg(4) interface */
 246 int ifconfig_lagg_get_lagg_status(ifconfig_handle_t *h,
 247     const char *name, struct ifconfig_lagg_status **lagg_status);
 248
 249 /** Retrieve additional information about a member of a lagg(4) interface */
 250 int ifconfig_lagg_get_laggport_status(ifconfig_handle_t *h,
 251     const char *name, struct lagg_reqport *rp);
 252
 253 /** Frees the structure returned by ifconfig_lagg_get_lagg_status.  Does
 254  * nothing if the argument is NULL
 255  * @param laggstat      Pointer to the structure to free
 256  */
 257 void ifconfig_lagg_free_lagg_status(struct ifconfig_lagg_status *laggstat);
 258
 259 /** Destroy a virtual interface
 260  * @param name Interface to destroy
 261  */
 262 int ifconfig_destroy_interface(ifconfig_handle_t *h, const char *name);
 263
 264 /** Creates a (virtual) interface
 265  * @param name Name of interface to create. Example: bridge or bridge42
 266  * @param name ifname Is set to actual name of created interface
 267  */
 268 int ifconfig_create_interface(ifconfig_handle_t *h, const char *name,
 269     char **ifname);
 270
 271 /** Creates a (virtual) interface
 272  * @param name Name of interface to create. Example: vlan0 or ix0.50
 273  * @param name ifname Is set to actual name of created interface
 274  * @param vlandev Name of interface to attach to
 275  * @param vlanid VLAN ID/Tag. Must not be 0.
 276  */
 277 int ifconfig_create_interface_vlan(ifconfig_handle_t *h, const char *name,
 278     char **ifname, const char *vlandev, const unsigned short vlantag);
 279
 280 int ifconfig_set_vlantag(ifconfig_handle_t *h, const char *name,
 281     const char *vlandev, const unsigned short vlantag);
 282
 283 /** Gets the names of all interface cloners available on the system
 284  * @param bufp  Set to the address of the names buffer on success or NULL
 285  *              if an error occurs.  This buffer must be freed when done.
 286  * @param lenp  Set to the number of names in the returned buffer or 0
 287  *              if an error occurs.  Each name is contained within an
 288  *              IFNAMSIZ length slice of the buffer, for a total buffer
 289  *              length of *lenp * IFNAMSIZ bytes.
 290  */
 291 int ifconfig_list_cloners(ifconfig_handle_t *h, char **bufp, size_t *lenp);