libosmocore 1.13.1.1-afb4 Osmocom core library

Files | Data Structures | Macros | Functions | Variables
Netdev

network device (interface) convenience functions More...

## Files
file | netdev.c
| Example lifecycle use of the API:

## Data Structures
struct | netdev_netns_ctx
struct | osmo_netdev

## Macros
#define | IFINDEX_UNUSED 0
#define | LOGNETDEV(netdev, lvl, fmt, args ...)
#define | NETDEV_NETNS_ENTER(netdev, switch_state, str_prefix)
#define | NETDEV_NETNS_EXIT(netdev, switch_state, str_prefix)

## Functions
static struct netdev_netns_ctx * | netdev_netns_ctx_alloc (void *ctx, const char *netns_name)
static void | netdev_netns_ctx_free (struct netdev_netns_ctx *netns_ctx)
static int | netdev_netns_ctx_init (struct netdev_netns_ctx *netns_ctx)
static struct netdev_netns_ctx * | netdev_netns_ctx_find_by_netns_name (const char *netns_name)
static struct netdev_netns_ctx * | netdev_netns_ctx_get (const char *netns_name)
static void | netdev_netns_ctx_put (struct netdev_netns_ctx *netns_ctx)
struct osmo_netdev * | osmo_netdev_alloc (void *ctx, const char *name)
| Allocate a new netdev object. More...
void | osmo_netdev_free (struct osmo_netdev *netdev)
| Free an allocated netdev object. More...
int | osmo_netdev_register (struct osmo_netdev *netdev)
| Start managing the network device referenced by the netdev object. More...
int | osmo_netdev_unregister (struct osmo_netdev *netdev)
| Unregister the netdev object (stop managing /moniutoring the interface) More...
bool | osmo_netdev_is_registered (struct osmo_netdev *netdev)
| Retrieve whether the netdev object is in "registered" state. More...
void | osmo_netdev_set_priv_data (struct osmo_netdev *netdev, void *priv_data)
| Set private user data pointer on the netdev object. More...
void * | osmo_netdev_get_priv_data (struct osmo_netdev *netdev)
| Get private user data pointer from the netdev object. More...
void | osmo_netdev_set_ifupdown_ind_cb (struct osmo_netdev *netdev, osmo_netdev_ifupdown_ind_cb_t ifupdown_ind_cb)
| Set ifupdown_ind_cb callback, called when the link status (UP/DOWN) changes. More...
void | osmo_netdev_set_dev_name_chg_cb (struct osmo_netdev *netdev, osmo_netdev_dev_name_chg_cb_t dev_name_chg_cb)
| Set dev_name_chg_cb callback, called when a change in the network name is detected. More...
void | osmo_netdev_set_mtu_chg_cb (struct osmo_netdev *netdev, osmo_netdev_mtu_chg_cb_t mtu_chg_cb)
| Set mtu_chg_cb callback, called when a change in the network name is detected. More...
const char * | osmo_netdev_get_name (const struct osmo_netdev *netdev)
| Get name used to identify the netdev object. More...
int | osmo_netdev_set_ifindex (struct osmo_netdev *netdev, unsigned int ifindex)
| Set (specify) interface index identifying the network interface to manage. More...
unsigned int | osmo_netdev_get_ifindex (const struct osmo_netdev *netdev)
| Get interface index identifying the interface managed by netdev. More...
int | osmo_netdev_set_netns_name (struct osmo_netdev *netdev, const char *netns_name)
| Set (specify) name of the network namespace where the network interface to manage is located. More...
const char * | osmo_netdev_get_netns_name (const struct osmo_netdev *netdev)
| Get name of network namespace used when opening the netdev interface. More...
const char * | osmo_netdev_get_dev_name (const struct osmo_netdev *netdev)
| Get name used to name the network interface created by the netdev object. More...
int | osmo_netdev_set_mtu (struct osmo_netdev *netdev, uint32_t mtu)
| Set the MTU of the network interface. More...
int | osmo_netdev_ifupdown (struct osmo_netdev *netdev, bool ifupdown)
| Bring netdev interface UP or DOWN. More...
int | osmo_netdev_add_addr (struct osmo_netdev *netdev, const struct osmo_sockaddr *addr, uint8_t prefixlen)
| Add IP address to netdev interface. More...
int | osmo_netdev_add_route (struct osmo_netdev *netdev, const struct osmo_sockaddr *dst_addr, uint8_t dst_prefixlen, const struct osmo_sockaddr *gw_addr)
| Add IP route to netdev interface. More...

## Variables
static struct llist_head | g_netdev_netns_ctx_list = LLIST_HEAD_INIT(g_netdev_netns_ctx_list)
static struct llist_head | g_netdev_list = LLIST_HEAD_INIT(g_netdev_list)

## Detailed Description

network device (interface) convenience functions

## Macro Definition Documentation

## ◆ IFINDEX_UNUSED

#define IFINDEX_UNUSED 0

## ◆ LOGNETDEV

#define LOGNETDEV | ( |  | netdev,
|  |  | lvl,
|  |  | fmt,
|  |  | args ...
| ) |  |

Value:
LOGP(DLGLOBAL, lvl, "NETDEV(%s,if=%s/%u,ns=%s): " fmt, \
(netdev)->name, osmo_netdev_get_dev_name(netdev) ? : "", \
(netdev)->ifindex, (netdev)->netns_name ? : "", ## args)
name
const char * name
DLGLOBAL
#define DLGLOBAL
global logging
Definition: logging.h:129
LOGP
#define LOGP(ss, level, fmt, args...)
Log a new message through the Osmocom logging framework.
Definition: logging.h:49
osmo_netdev_get_dev_name
const char * osmo_netdev_get_dev_name(const struct osmo_netdev *netdev)
Get name used to name the network interface created by the netdev object.
Definition: netdev.c:888

## ◆ NETDEV_NETNS_ENTER

#define NETDEV_NETNS_ENTER | ( |  | netdev,
|  |  | switch_state,
|  |  | str_prefix
| ) |  |

Value:
do { \
if ((netdev)->netns_name) { \
LOGNETDEV(netdev, LOGL_DEBUG, str_prefix ": Switch to netns '%s'\n", \
(netdev)->netns_name); \
int rc2 = osmo_netns_switch_enter((netdev)->netns_ctx->netns_fd, switch_state); \
if (rc2 < 0) { \
LOGNETDEV(netdev, LOGL_ERROR, str_prefix ": Cannot switch to netns '%s': %s (%d)\n", \
(netdev)->netns_name, strerror(errno), errno); \
return -EACCES; \
} \
} \
} while (0)
LOGL_ERROR
#define LOGL_ERROR
error condition, requires user action
Definition: logging.h:125
LOGL_DEBUG
#define LOGL_DEBUG
different log levels
Definition: logging.h:122
osmo_netns_switch_enter
int osmo_netns_switch_enter(int nsfd, struct osmo_netns_switch_state *state)
switch to a (non-default) namespace, store existing signal mask in oldmask.
Definition: netns.c:80

## ◆ NETDEV_NETNS_EXIT

#define NETDEV_NETNS_EXIT | ( |  | netdev,
|  |  | switch_state,
|  |  | str_prefix
| ) |  |

Value:
do { \
if ((netdev)->netns_name) { \
int rc2 = osmo_netns_switch_exit(switch_state); \
if (rc2 < 0) { \
LOGNETDEV(netdev, LOGL_ERROR, str_prefix ": Cannot switch back from netns '%s': %s\n", \
(netdev)->netns_name, strerror(errno)); \
return rc2; \
} \
LOGNETDEV(netdev, LOGL_DEBUG, str_prefix ": Back from netns '%s'\n", \
(netdev)->netns_name); \
} \
} while (0)
osmo_netns_switch_exit
int osmo_netns_switch_exit(struct osmo_netns_switch_state *state)
switch back to the previous namespace, restoring signal mask.
Definition: netns.c:110

## Function Documentation

## ◆ netdev_netns_ctx_alloc()

static struct netdev_netns_ctx * netdev_netns_ctx_alloc | ( | void * | ctx,
|  | const char * | netns_name
| ) |  |
| static

References netdev_netns_ctx::entry, g_netdev_netns_ctx_list, llist_add_tail(), netdev_netns_ctx::netns_fd, netdev_netns_ctx::netns_name, and OSMO_ASSERT.

Referenced by netdev_netns_ctx_get().

## ◆ netdev_netns_ctx_find_by_netns_name()

static struct netdev_netns_ctx * netdev_netns_ctx_find_by_netns_name | ( | const char * | netns_name | ) |
| static

References netdev_netns_ctx::entry, g_netdev_netns_ctx_list, llist_for_each_entry, and netdev_netns_ctx::netns_name.

Referenced by netdev_netns_ctx_get().

## ◆ netdev_netns_ctx_free()

static void netdev_netns_ctx_free | ( | struct netdev_netns_ctx * | netns_ctx | ) |
| static

References netdev_netns_ctx::entry, llist_del(), netdev_netns_ctx::netns_fd, and osmo_mnl_destroy().

Referenced by netdev_netns_ctx_get(), and netdev_netns_ctx_put().

## ◆ netdev_netns_ctx_get()

static struct netdev_netns_ctx * netdev_netns_ctx_get | ( | const char * | netns_name | ) |
| static

References netdev_netns_ctx_alloc(), netdev_netns_ctx_find_by_netns_name(), netdev_netns_ctx_free(), netdev_netns_ctx_init(), netdev_netns_ctx::netns_name, OSMO_ASSERT, and netdev_netns_ctx::refcount.

Referenced by osmo_netdev_register().

## ◆ netdev_netns_ctx_init()

static int netdev_netns_ctx_init | ( | struct netdev_netns_ctx * | netns_ctx | ) |
| static

References DLGLOBAL, LOGL_ERROR, LOGL_INFO, LOGP, netdev_netns_ctx::netns_fd, netdev_netns_ctx::netns_name, osmo_mnl_init(), osmo_netns_open_fd(), osmo_netns_switch_enter(), and osmo_netns_switch_exit().

Referenced by netdev_netns_ctx_get().

## ◆ netdev_netns_ctx_put()

static void netdev_netns_ctx_put | ( | struct netdev_netns_ctx * | netns_ctx | ) |
| static

References netdev_netns_ctx_free(), OSMO_ASSERT, and netdev_netns_ctx::refcount.

Referenced by osmo_netdev_register(), and osmo_netdev_unregister().

## ◆ osmo_netdev_add_addr()

int osmo_netdev_add_addr | ( | struct osmo_netdev * | netdev,
|  | const struct osmo_sockaddr * | addr,
|  | uint8_t | prefixlen
| ) |  |

Add IP address to netdev interface.

Parameters

  [in] | netdev | The netdev object managing the netdev interface
  [in] | addr | The local address to set on the interface
  [in] | prefixlen | The network prefix of addr

Returns
  0 on succes; negative on error.

References osmo_netdev::dev_name, ENOTSUP, osmo_netdev::ifindex, LOGL_ERROR, LOGL_NOTICE, LOGNETDEV, NETDEV_NETNS_ENTER, NETDEV_NETNS_EXIT, osmo_netdev::netns_ctx, osmo_sockaddr_ntop(), osmo_netdev::registered, osmo_sockaddr::sa, and osmo_sockaddr::u.

## ◆ osmo_netdev_add_route()

int osmo_netdev_add_route | ( | struct osmo_netdev * | netdev,
|  | const struct osmo_sockaddr * | dst_addr,
|  | uint8_t | dst_prefixlen,
|  | const struct osmo_sockaddr * | gw_addr
| ) |  |

Add IP route to netdev interface.

Parameters

  [in] | netdev | The netdev object managing the netdev interface
  [in] | dst_addr | The destination address of the route
  [in] | dst_prefixlen | The network prefix of dst_addr
  [in] | gw_addr | The gateway address. Optional, can be NULL.

Returns
  0 on succes; negative on error.

References osmo_netdev::dev_name, ENOTSUP, osmo_netdev::ifindex, LOGL_ERROR, LOGL_NOTICE, LOGNETDEV, NETDEV_NETNS_ENTER, NETDEV_NETNS_EXIT, osmo_netdev::netns_ctx, osmo_sockaddr_ntop(), osmo_netdev::registered, osmo_sockaddr::sa, and osmo_sockaddr::u.

## ◆ osmo_netdev_alloc()

struct osmo_netdev * osmo_netdev_alloc | ( | void * | ctx,
|  | const char * | name
| ) |  |

Allocate a new netdev object.

Parameters

  [in] | ctx | talloc context to use as a parent when allocating the netdev object
  [in] | name | A name providen to identify the netdev object

Returns
  newly allocated netdev object on success; NULL on error

References osmo_netdev::entry, g_netdev_list, llist_add_tail(), name, and osmo_netdev::name.

Referenced by osmo_tundev_alloc().

## ◆ osmo_netdev_free()

void osmo_netdev_free | ( | struct osmo_netdev * | netdev | ) |

Free an allocated netdev object.

Parameters

  [in] | netdev | The netdev object to free

References osmo_netdev::entry, llist_del(), osmo_netdev_is_registered(), and osmo_netdev_unregister().

Referenced by osmo_tundev_free().

## ◆ osmo_netdev_get_dev_name()

const char * osmo_netdev_get_dev_name | ( | const struct osmo_netdev * | netdev | ) |

Get name used to name the network interface created by the netdev object.

Parameters

  [in] | netdev | The netdev object from where to retrieve the field

Returns
  The interface name (or NULL if unknown)

This information is retrieved internally once the netdev object enters the "registered" state. Hence, when not registered NULL can be returned.

References osmo_netdev::dev_name.

Referenced by tundev_dev_name_chg_cb().

## ◆ osmo_netdev_get_ifindex()

unsigned int osmo_netdev_get_ifindex | ( | const struct osmo_netdev * | netdev | ) |

Get interface index identifying the interface managed by netdev.

Parameters

  [in] | netdev | The netdev object from where to retrieve the field

Returns
  The current value of the configured netdev interface ifindex to use (0 = unset)

References osmo_netdev::ifindex.

## ◆ osmo_netdev_get_name()

const char * osmo_netdev_get_name | ( | const struct osmo_netdev * | netdev | ) |

Get name used to identify the netdev object.

Parameters

  [in] | netdev | The netdev object from where to retrieve the field

Returns
  The current value of the name used to identify the netdev object

References osmo_netdev::name.

## ◆ osmo_netdev_get_netns_name()

const char * osmo_netdev_get_netns_name | ( | const struct osmo_netdev * | netdev | ) |

Get name of network namespace used when opening the netdev interface.

Parameters

  [in] | netdev | The netdev object from where to retrieve the field

Returns
  The current value of the configured network namespace

References osmo_netdev::netns_name.

## ◆ osmo_netdev_get_priv_data()

void * osmo_netdev_get_priv_data | ( | struct osmo_netdev * | netdev | ) |

Get private user data pointer from the netdev object.

Parameters

  [in] | netdev | The netdev object from where to retrieve the field

Returns
  The current value of the priv_data field.

References osmo_netdev::priv_data.

Referenced by tundev_dev_name_chg_cb(), tundev_ifupdown_ind_cb(), and tundev_mtu_chg_cb().

## ◆ osmo_netdev_ifupdown()

int osmo_netdev_ifupdown | ( | struct osmo_netdev * | netdev,
|  | bool | ifupdown
| ) |  |

Bring netdev interface UP or DOWN.

Parameters

  [in] | netdev | The netdev object managing the netdev interface
  [in] | ifupdown | true to set the interface UP, false to set it DOWN

Returns
  0 on succes; negative on error.

References osmo_netdev::dev_name, ENOTSUP, osmo_netdev::ifindex, LOGL_ERROR, LOGL_NOTICE, LOGNETDEV, NETDEV_NETNS_ENTER, NETDEV_NETNS_EXIT, osmo_netdev::netns_ctx, and osmo_netdev::registered.

## ◆ osmo_netdev_is_registered()

bool osmo_netdev_is_registered | ( | struct osmo_netdev * | netdev | ) |

Retrieve whether the netdev object is in "registered" state.

Parameters

  [in] | netdev | The netdev object to check

Returns
  true if in state "registered"; false otherwise

References osmo_netdev::registered.

Referenced by osmo_netdev_free().

## ◆ osmo_netdev_register()

int osmo_netdev_register | ( | struct osmo_netdev * | netdev | ) |

Start managing the network device referenced by the netdev object.

Parameters

  [in] | netdev | The netdev object to open

Returns
  0 on success; negative on error

References osmo_netdev::dev_name, osmo_netdev::ifindex, netdev_netns_ctx_get(), netdev_netns_ctx_put(), NETDEV_NETNS_ENTER, NETDEV_NETNS_EXIT, osmo_netdev::netns_ctx, osmo_netdev::netns_name, osmo_talloc_replace_string(), and osmo_netdev::registered.

Referenced by osmo_tundev_open().

## ◆ osmo_netdev_set_dev_name_chg_cb()

void osmo_netdev_set_dev_name_chg_cb | ( | struct osmo_netdev * | netdev,
|  | osmo_netdev_dev_name_chg_cb_t | dev_name_chg_cb
| ) |  |

Set dev_name_chg_cb callback, called when a change in the network name is detected.

Parameters

  [in] | netdev | The netdev object where the field is set
  [in] | dev_name_chg_cb | the user provided function to be called when a the interface is renamed

References osmo_netdev::dev_name_chg_cb.

Referenced by osmo_tundev_alloc().

## ◆ osmo_netdev_set_ifindex()

int osmo_netdev_set_ifindex | ( | struct osmo_netdev * | netdev,
|  | unsigned int | ifindex
| ) |  |

Set (specify) interface index identifying the network interface to manage.

Parameters

  [in] | netdev | The netdev object where the field is set
  [in] | ifindex | The interface index identifying the interface

Returns
  0 on success; negative on error

The ifindex, together with the netns_name (see osmo_netdev_netns_name_set()), form together the key identifiers of a network interface to manage. This field is used during osmo_netdev_register() time, and hence must be set before calling that API, and cannot be changed when the netdev object is in "registered" state.

References osmo_netdev::ifindex, and osmo_netdev::registered.

Referenced by osmo_tundev_open().

## ◆ osmo_netdev_set_ifupdown_ind_cb()

void osmo_netdev_set_ifupdown_ind_cb | ( | struct osmo_netdev * | netdev,
|  | osmo_netdev_ifupdown_ind_cb_t | ifupdown_ind_cb
| ) |  |

Set ifupdown_ind_cb callback, called when the link status (UP/DOWN) changes.

Parameters

  [in] | netdev | The netdev object where the field is set
  [in] | ifupdown_ind_cb | the user provided function to be called when the link status (UP/DOWN) changes

References osmo_netdev::ifupdown_ind_cb.

Referenced by osmo_tundev_alloc().

## ◆ osmo_netdev_set_mtu()

int osmo_netdev_set_mtu | ( | struct osmo_netdev * | netdev,
|  | uint32_t | mtu
| ) |  |

Set the MTU of the network interface.

Parameters

  [in] | netdev | The netdev object where the field is set
  [in] | mtu | The MTU to be set on the network interface

Returns
  0 on success; negative on error

References osmo_netdev::dev_name, ENOTSUP, osmo_netdev::ifindex, LOGL_ERROR, LOGL_NOTICE, LOGNETDEV, NETDEV_NETNS_ENTER, NETDEV_NETNS_EXIT, osmo_netdev::netns_ctx, and osmo_netdev::registered.

## ◆ osmo_netdev_set_mtu_chg_cb()

void osmo_netdev_set_mtu_chg_cb | ( | struct osmo_netdev * | netdev,
|  | osmo_netdev_mtu_chg_cb_t | mtu_chg_cb
| ) |  |

Set mtu_chg_cb callback, called when a change in the network name is detected.

Parameters

  [in] | netdev | The netdev object where the field is set
  [in] | mtu_chg_cb | the user provided function to be called when the configured MTU at the interface changes

References osmo_netdev::mtu_chg_cb.

Referenced by osmo_tundev_alloc().

## ◆ osmo_netdev_set_netns_name()

int osmo_netdev_set_netns_name | ( | struct osmo_netdev * | netdev,
|  | const char * | netns_name
| ) |  |

Set (specify) name of the network namespace where the network interface to manage is located.

Parameters

  [in] | netdev | The netdev object where the field is set
  [in] | netns_name | The network namespace where the network interface is located

Returns
  0 on success; negative on error

The netns_name, together with the ifindex (see osmo_netdev_ifindex_set()), form together the key identifiers of a network interface to manage. This field is used during osmo_netdev_register() time, and hence must be set before calling that API, and cannot be changed when the netdev object is in "registered" state. If left as NULL (default), the management will be done in the current network namespace.

References osmo_netdev::netns_name, osmo_talloc_replace_string(), and osmo_netdev::registered.

Referenced by osmo_tundev_open().

## ◆ osmo_netdev_set_priv_data()

void osmo_netdev_set_priv_data | ( | struct osmo_netdev * | netdev,
|  | void * | priv_data
| ) |  |

Set private user data pointer on the netdev object.

Parameters

  [in] | netdev | The netdev object where the field is set

References osmo_netdev::priv_data.

Referenced by osmo_tundev_alloc().

## ◆ osmo_netdev_unregister()

int osmo_netdev_unregister | ( | struct osmo_netdev * | netdev | ) |

Unregister the netdev object (stop managing /moniutoring the interface)

Parameters

  [in] | netdev | The netdev object to close

Returns
  0 on success; negative on error

References osmo_netdev::if_mtu_known, osmo_netdev::if_up_known, netdev_netns_ctx_put(), osmo_netdev::netns_ctx, and osmo_netdev::registered.

Referenced by osmo_netdev_free(), osmo_tundev_close(), and osmo_tundev_open().

## Variable Documentation

## ◆ g_netdev_list

struct llist_head g_netdev_list = LLIST_HEAD_INIT(g_netdev_list)
| static

Referenced by osmo_netdev_alloc().

## ◆ g_netdev_netns_ctx_list

struct llist_head g_netdev_netns_ctx_list = LLIST_HEAD_INIT(g_netdev_netns_ctx_list)
| static

Referenced by netdev_netns_ctx_alloc(), and netdev_netns_ctx_find_by_netns_name().