2 * Copyright (c) 2016-2017, Marie Helene Kvello-Aune
5 * Redistribution and use in source and binary forms, with or without modification,
6 * are permitted provided that the following conditions are met:
8 * 1. Redistributions of source code must retain the above copyright notice,
9 * thislist of conditions and the following disclaimer.
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.
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.
29 #include <sys/types.h>
33 #include <netinet/in.h>
34 #include <netinet/ip_carp.h>
35 #include <netinet6/in6_var.h>
37 #define ND6_IFF_DEFAULTIF 0x8000
48 * Opaque definition so calling application can just pass a
49 * pointer to it for library use.
51 struct ifconfig_handle;
52 typedef struct ifconfig_handle ifconfig_handle_t;
63 /** Stores extra info associated with a bridge(4) interface */
64 struct ifconfig_bridge_status {
65 struct ifbropreq *params; /**< current operational parameters */
66 struct ifbreq *members; /**< list of bridge members */
67 size_t members_count; /**< how many member interfaces */
68 uint32_t cache_size; /**< size of address cache */
69 uint32_t cache_lifetime; /**< address cache entry lifetime */
72 struct ifconfig_capabilities {
73 /** Current capabilities (ifconfig prints this as 'options')*/
75 /** Requested capabilities (ifconfig prints this as 'capabilities')*/
79 /** Stores extra info associated with an inet address */
80 struct ifconfig_inet_addr {
81 const struct sockaddr_in *sin;
82 const struct sockaddr_in *netmask;
83 const struct sockaddr_in *dst;
84 const struct sockaddr_in *broadcast;
89 /** Stores extra info associated with an inet6 address */
90 struct ifconfig_inet6_addr {
91 struct sockaddr_in6 *sin6;
92 struct sockaddr_in6 *dstin6;
93 struct in6_addrlifetime lifetime;
99 /** Stores extra info associated with a lagg(4) interface */
100 struct ifconfig_lagg_status {
101 struct lagg_reqall *ra;
102 struct lagg_reqopts *ro;
103 struct lagg_reqflags *rf;
106 /** Retrieves a new state object for use in other API calls.
109 * // Create state object
110 * ifconfig_handle_t *lifh;
111 * lifh = ifconfig_open();
112 * if (lifh == NULL) {
116 * // Do stuff with the handle
118 * // Dispose of the state object
119 * ifconfig_close(lifh);
123 ifconfig_handle_t *ifconfig_open(void);
125 /** Frees resources held in the provided state object.
126 * @param h The state object to close.
127 * @see #ifconfig_open(void)
129 void ifconfig_close(ifconfig_handle_t *h);
131 /** Identifies what kind of error occurred. */
132 ifconfig_errtype ifconfig_err_errtype(ifconfig_handle_t *h);
134 /** Retrieves the errno associated with the error, if any. */
135 int ifconfig_err_errno(ifconfig_handle_t *h);
137 typedef void (*ifconfig_foreach_func_t)(ifconfig_handle_t *h,
138 struct ifaddrs *ifa, void *udata);
140 /** Iterate over every network interface
141 * @param h An open ifconfig state object
142 * @param cb A callback function to call with a pointer to each interface
143 * @param udata An opaque value that will be passed to the callback.
144 * @return 0 on success, nonzero if the list could not be iterated
146 int ifconfig_foreach_iface(ifconfig_handle_t *h, ifconfig_foreach_func_t cb,
149 /** Iterate over every address on a single network interface
150 * @param h An open ifconfig state object
151 * @param ifa A pointer that was supplied by a previous call to
152 * ifconfig_foreach_iface
153 * @param udata An opaque value that will be passed to the callback.
154 * @param cb A callback function to call with a pointer to each ifaddr
156 void ifconfig_foreach_ifaddr(ifconfig_handle_t *h, struct ifaddrs *ifa,
157 ifconfig_foreach_func_t cb, void *udata);
159 /** If error type was IOCTL, this identifies which request failed. */
160 unsigned long ifconfig_err_ioctlreq(ifconfig_handle_t *h);
161 int ifconfig_get_description(ifconfig_handle_t *h, const char *name,
163 int ifconfig_set_description(ifconfig_handle_t *h, const char *name,
164 const char *newdescription);
165 int ifconfig_unset_description(ifconfig_handle_t *h, const char *name);
166 int ifconfig_set_name(ifconfig_handle_t *h, const char *name,
167 const char *newname);
168 int ifconfig_get_orig_name(ifconfig_handle_t *h, const char *ifname,
170 int ifconfig_set_fib(ifconfig_handle_t *h, const char *name, int fib);
171 int ifconfig_get_fib(ifconfig_handle_t *h, const char *name, int *fib);
172 int ifconfig_set_mtu(ifconfig_handle_t *h, const char *name, const int mtu);
173 int ifconfig_get_mtu(ifconfig_handle_t *h, const char *name, int *mtu);
174 int ifconfig_get_nd6(ifconfig_handle_t *h, const char *name,
175 struct in6_ndireq *nd);
176 int ifconfig_set_metric(ifconfig_handle_t *h, const char *name,
178 int ifconfig_get_metric(ifconfig_handle_t *h, const char *name, int *metric);
179 int ifconfig_set_capability(ifconfig_handle_t *h, const char *name,
180 const int capability);
181 int ifconfig_get_capability(ifconfig_handle_t *h, const char *name,
182 struct ifconfig_capabilities *capability);
184 /** Retrieve the list of groups to which this interface belongs
185 * @param h An open ifconfig state object
186 * @param name The interface name
187 * @param ifgr return argument. The caller is responsible for freeing
189 * @return 0 on success, nonzero on failure
191 int ifconfig_get_groups(ifconfig_handle_t *h, const char *name,
192 struct ifgroupreq *ifgr);
193 int ifconfig_get_ifstatus(ifconfig_handle_t *h, const char *name,
194 struct ifstat *stat);
196 /** Retrieve the interface media information
197 * @param h An open ifconfig state object
198 * @param name The interface name
199 * @param ifmr Return argument. The caller is responsible for freeing it
200 * @return 0 on success, nonzero on failure
202 int ifconfig_media_get_mediareq(ifconfig_handle_t *h, const char *name,
203 struct ifmediareq **ifmr);
205 const char *ifconfig_media_get_status(const struct ifmediareq *ifmr);
207 typedef int ifmedia_t;
209 #define INVALID_IFMEDIA ((ifmedia_t)-1)
211 /** Retrieve the name of a media type
212 * @param media The media to be named
213 * @return A pointer to the media type name, or NULL on failure
215 const char *ifconfig_media_get_type(ifmedia_t media);
217 /** Retrieve a media type by its name
218 * @param name The name of a media type
219 * @return The media type value, or INVALID_IFMEDIA on failure
221 ifmedia_t ifconfig_media_lookup_type(const char *name);
223 /** Retrieve the name of a media subtype
224 * @param media The media subtype to be named
225 * @return A pointer to the media subtype name, or NULL on failure
227 const char *ifconfig_media_get_subtype(ifmedia_t media);
229 /** Retrieve a media subtype by its name
230 * @param media The top level media type whose subtype we want
231 * @param name The name of a media subtype
232 * @return The media subtype value, or INVALID_IFMEDIA on failure
234 ifmedia_t ifconfig_media_lookup_subtype(ifmedia_t media, const char *name);
236 /** Retrieve the name of a media mode
237 * @param media The media mode to be named
238 * @return A pointer to the media mode name, or NULL on failure
240 const char *ifconfig_media_get_mode(ifmedia_t media);
242 /** Retrieve a media mode by its name
243 * @param media The top level media type whose mode we want
244 * @param name The name of a media mode
245 * @return The media mode value, or INVALID_IFMEDIA on failure
247 ifmedia_t ifconfig_media_lookup_mode(ifmedia_t media, const char *name);
249 /** Retrieve an array of media options
250 * @param media The media for which to obtain the options
251 * @return Pointer to an array of pointers to option names,
252 * terminated by a NULL pointer, or simply NULL on failure.
253 * The caller is responsible for freeing the array but not its
256 const char **ifconfig_media_get_options(ifmedia_t media);
258 /** Retrieve an array of media options by names
259 * @param media The top level media type whose options we want
260 * @param opts Pointer to an array of string pointers naming options
261 * @param nopts Number of elements in the opts array
262 * @return Pointer to an array of media options, one for each option named
263 * in opts. NULL is returned instead with errno set to ENOMEM if
264 * allocating the return array fails or EINVAL if media is not
265 * valid. A media option in the array will be INVALID_IFMEDIA
266 * when lookup failed for the option named in that position in
267 * opts. The caller is responsible for freeing the array.
269 ifmedia_t *ifconfig_media_lookup_options(ifmedia_t media, const char **opts,
272 /** Retrieve the reason the interface is down
273 * @param h An open ifconfig state object
274 * @param name The interface name
275 * @param ifdr Return argument.
276 * @return 0 on success, nonzero on failure
278 int ifconfig_media_get_downreason(ifconfig_handle_t *h, const char *name,
279 struct ifdownreason *ifdr);
281 struct ifconfig_carp {
284 uint32_t carpr_state;
285 int32_t carpr_advbase;
286 int32_t carpr_advskew;
287 uint8_t carpr_key[CARP_KEY_LEN];
288 struct in_addr carpr_addr;
289 struct in6_addr carpr_addr6;
292 int ifconfig_carp_get_vhid(ifconfig_handle_t *h, const char *name,
293 struct ifconfig_carp *carpr, uint32_t vhid);
294 int ifconfig_carp_get_info(ifconfig_handle_t *h, const char *name,
295 struct ifconfig_carp *carpr, size_t ncarp);
296 int ifconfig_carp_set_info(ifconfig_handle_t *h, const char *name,
297 const struct ifconfig_carp *carpr);
299 /** Retrieve additional information about an inet address
300 * @param h An open ifconfig state object
301 * @param name The interface name
302 * @param ifa Pointer to the address structure of interest
303 * @param addr Return argument. It will be filled with additional information
305 * @return 0 on success, nonzero on failure.
307 int ifconfig_inet_get_addrinfo(ifconfig_handle_t *h,
308 const char *name, struct ifaddrs *ifa, struct ifconfig_inet_addr *addr);
310 /** Retrieve additional information about an inet6 address
311 * @param h An open ifconfig state object
312 * @param name The interface name
313 * @param ifa Pointer to the address structure of interest
314 * @param addr Return argument. It will be filled with additional information
316 * @return 0 on success, nonzero on failure.
318 int ifconfig_inet6_get_addrinfo(ifconfig_handle_t *h,
319 const char *name, struct ifaddrs *ifa, struct ifconfig_inet6_addr *addr);
321 /** Retrieve additional information about a bridge(4) interface */
322 int ifconfig_bridge_get_bridge_status(ifconfig_handle_t *h,
323 const char *name, struct ifconfig_bridge_status **bridge);
325 /** Frees the structure returned by ifconfig_bridge_get_bridge_status. Does
326 * nothing if the argument is NULL
327 * @param bridge Pointer to the structure to free
329 void ifconfig_bridge_free_bridge_status(struct ifconfig_bridge_status *bridge);
331 /** Retrieve additional information about a lagg(4) interface */
332 int ifconfig_lagg_get_lagg_status(ifconfig_handle_t *h,
333 const char *name, struct ifconfig_lagg_status **lagg_status);
335 /** Retrieve additional information about a member of a lagg(4) interface */
336 int ifconfig_lagg_get_laggport_status(ifconfig_handle_t *h,
337 const char *name, struct lagg_reqport *rp);
339 /** Frees the structure returned by ifconfig_lagg_get_lagg_status. Does
340 * nothing if the argument is NULL
341 * @param laggstat Pointer to the structure to free
343 void ifconfig_lagg_free_lagg_status(struct ifconfig_lagg_status *laggstat);
345 /** Destroy a virtual interface
346 * @param name Interface to destroy
348 int ifconfig_destroy_interface(ifconfig_handle_t *h, const char *name);
350 /** Creates a (virtual) interface
351 * @param name Name of interface to create. Example: bridge or bridge42
352 * @param name ifname Is set to actual name of created interface
354 int ifconfig_create_interface(ifconfig_handle_t *h, const char *name,
357 /** Creates a (virtual) interface
358 * @param name Name of interface to create. Example: vlan0 or ix0.50
359 * @param name ifname Is set to actual name of created interface
360 * @param vlandev Name of interface to attach to
361 * @param vlanid VLAN ID/Tag. Must not be 0.
363 int ifconfig_create_interface_vlan(ifconfig_handle_t *h, const char *name,
364 char **ifname, const char *vlandev, const unsigned short vlantag);
366 int ifconfig_set_vlantag(ifconfig_handle_t *h, const char *name,
367 const char *vlandev, const unsigned short vlantag);
369 /** Gets the names of all interface cloners available on the system
370 * @param bufp Set to the address of the names buffer on success or NULL
371 * if an error occurs. This buffer must be freed when done.
372 * @param lenp Set to the number of names in the returned buffer or 0
373 * if an error occurs. Each name is contained within an
374 * IFNAMSIZ length slice of the buffer, for a total buffer
375 * length of *lenp * IFNAMSIZ bytes.
377 int ifconfig_list_cloners(ifconfig_handle_t *h, char **bufp, size_t *lenp);