libosmoctrl 1.13.1.1-afb4 Osmocom CTRL library

Macros | Functions | Variables
control_cmd.c File Reference

SNMP-like status interface. More...

`#include <ctype.h>`
`#include <errno.h>`
`#include <stdio.h>`
`#include <stdlib.h>`
`#include <string.h>`
`#include <time.h>`
`#include <unistd.h>`
`#include <osmocom/ctrl/control_cmd.h>`
`#include <osmocom/ctrl/control_if.h>`
`#include <osmocom/core/msgb.h>`
`#include <osmocom/core/talloc.h>`
`#include <osmocom/core/utils.h>`
`#include <osmocom/vty/command.h>`
`#include <osmocom/vty/vector.h>`

## Macros
#define | REPLY_CASE(TYPE, NAME)

## Functions
vector | cmd_make_descvec (const char *string, const char *descstr)
static struct ctrl_cmd_element * | ctrl_cmd_get_element_match (vector vline, vector node)
int | ctrl_cmd_exec (vector vline, struct ctrl_cmd *command, vector node, void *data)
| Execute a given received command. More...
static void | add_word (struct ctrl_cmd_struct *cmd, const char *start, const char *end)
static void | create_cmd_struct (struct ctrl_cmd_struct *cmd, const char *name)
int | ctrl_cmd_install (enum ctrl_node_type node, struct ctrl_cmd_element *cmd)
| Install a given command definition at a given CTRL node. More...
struct ctrl_cmd * | ctrl_cmd_create (void *ctx, enum ctrl_type type)
| Allocate a control command of given type. More...
struct ctrl_cmd * | ctrl_cmd_cpy (void *ctx, struct ctrl_cmd *cmd)
| Perform a deepl copy of the given cmd, allocating memory from ctx. More...
struct ctrl_cmd * | ctrl_cmd_parse (void *ctx, struct msgb *msg)
| Parse/Decode CTRL from Message buffers into command struct. More...
static bool | id_str_valid (const char *str)
struct ctrl_cmd * | ctrl_cmd_parse2 (void *ctx, struct msgb *msg)
| Parse/Decode CTRL from Message buffers into command struct. More...
struct ctrl_cmd * | ctrl_cmd_parse3 (void *ctx, struct msgb *msg, bool *parse_failed)
| Parse/Decode CTRL from Message buffers into command struct. More...
struct msgb * | ctrl_cmd_make (struct ctrl_cmd *cmd)
| Encode a given CTRL command from its parsed form into a message buffer. More...
struct ctrl_cmd_def * | ctrl_cmd_def_make (const void *ctx, struct ctrl_cmd *cmd, void *data, unsigned int secs)
| Build a deferred control command state and keep it the per-connection list of deferred commands. More...
int | ctrl_cmd_def_is_zombie (struct ctrl_cmd_def *cd)
| Determine if the given deferred control command is still alive or a zombie. More...
int | ctrl_cmd_def_send (struct ctrl_cmd_def *cd)
| Send the response to a deferred ctrl command. More...

## Variables
vector | ctrl_node_vec
const struct value_string | ctrl_type_vals []
| human-readable string names for ctrl_type More...

## Detailed Description

SNMP-like status interface.

## Macro Definition Documentation

## ◆ REPLY_CASE

#define REPLY_CASE | ( |  | TYPE,
|  |  | NAME
| ) |  |

Value:
case TYPE: \
var = strtok_r(NULL, " ", &saveptr); \
val = strtok_r(NULL, "", &saveptr); \
if (!var) { \
cmd->type = CTRL_TYPE_ERROR; \
cmd->reply = NAME " incomplete"; \
LOGP(DLCTRL, LOGL_NOTICE, NAME " incomplete\n"); \
goto err; \
} \
if (!osmo_separated_identifiers_valid(var, ".")) { \
cmd->type = CTRL_TYPE_ERROR; \
cmd->reply = NAME " variable contains invalid characters"; \
LOGP(DLCTRL, LOGL_NOTICE, NAME " variable contains invalid characters: \"%s\"\n", \
osmo_escape_str(var, -1)); \
goto err; \
} \
cmd->variable = talloc_strdup(cmd, var); \
cmd->reply = talloc_strdup(cmd, val); \
if (!cmd->variable || !cmd->reply) \
goto oom; \
LOGP(DLCTRL, LOGL_DEBUG, "Command: " NAME " %s %s: %s\n", cmd->id, cmd->variable, \
osmo_escape_str(cmd->reply, -1)); \
break
CTRL_TYPE_ERROR
@ CTRL_TYPE_ERROR
Definition: control_cmd.h:39
osmo_escape_str
const char * osmo_escape_str(const char *str, int in_len)
osmo_separated_identifiers_valid
bool osmo_separated_identifiers_valid(const char *str, const char *sep_chars)

## Function Documentation

## ◆ add_word()

static void add_word | ( | struct ctrl_cmd_struct * | cmd,
|  | const char * | start,
|  | const char * | end
| ) |  |
| static

References ctrl_cmd_struct::command, ctrl_cmd_struct::nr_commands, start, and tall_vty_vec_ctx.

Referenced by create_cmd_struct().

## ◆ cmd_make_descvec()

vector cmd_make_descvec | ( | const char * | string,
|  | const char * | descstr
| ) |  |

## ◆ create_cmd_struct()

static void create_cmd_struct | ( | struct ctrl_cmd_struct * | cmd,
|  | const char * | name
| ) |  |
| static

References add_word(), ctrl_cmd_struct::command, DLCTRL, LOGL_ERROR, LOGP, name, and ctrl_cmd_struct::nr_commands.

Referenced by ctrl_cmd_install().

## ◆ ctrl_cmd_cpy()

struct ctrl_cmd * ctrl_cmd_cpy | ( | void * | ctx,
|  | struct ctrl_cmd * | cmd
| ) |  |

Perform a deepl copy of the given cmd, allocating memory from ctx.

Parameters

  [in] | ctx | talloc context from which to allocate
  | [in | cmd CTRL command to be copied

Returns
  deep copy of cmd on success; NULL on error

References ctrl_cmd::id, ctrl_cmd::reply, ctrl_cmd::type, ctrl_cmd::value, and ctrl_cmd::variable.

Referenced by ctrl_cmd_trap().

## ◆ ctrl_cmd_create()

struct ctrl_cmd * ctrl_cmd_create | ( | void * | ctx,
|  | enum ctrl_type | type
| ) |  |

Allocate a control command of given type.

Parameters

  [in] | ctx | talloc context from which to allocate
  [in] | type | command type to set after allocation

Returns
  callee-allocated ctrl_cmd. Caller must talloc_free() it.

References type, and ctrl_cmd::type.

Referenced by ctrl_cmd_send_trap().

## ◆ ctrl_cmd_def_is_zombie()

int ctrl_cmd_def_is_zombie | ( | struct ctrl_cmd_def * | cd | ) |

Determine if the given deferred control command is still alive or a zombie.

Parameters

  [in] | cd | deferred ctrl command state

Returns
  0 is cd is still alive; 1 if it's a zombie

References ctrl_cmd_def::cmd, ctrl_cmd_def::list, and llist_del().

## ◆ ctrl_cmd_def_make()

struct ctrl_cmd_def * ctrl_cmd_def_make | ( | const void * | ctx,
|  | struct ctrl_cmd * | cmd,
|  | void * | data,
|  | unsigned int | secs
| ) |  |

Build a deferred control command state and keep it the per-connection list of deferred commands.

This function is typically called by a ctrl command handler that wishes to defer returning a response. The reutnred state can later be used to check if the deferred command is still alive, and to respond to the specific command. This only works to defer the response to GET and SET.

Parameters

  [in] | ctx | talloc context from whihc to allocate the ctrl_cmd_def
  [in] | cmd | the control command whose response is deferred
  [in] | data | opaque, user-defined pointer
  [in] | secs | number of seconds until the command times out

Returns
  callee-allocated ctrl_cmd_def

References ctrl_cmd::ccon, ctrl_cmd_def::cmd, data, ctrl_cmd_def::data, ctrl_connection::def_cmds, ctrl_cmd::defer, ctrl_cmd_def::list, and llist_add().

## ◆ ctrl_cmd_def_send()

int ctrl_cmd_def_send | ( | struct ctrl_cmd_def * | cd | ) |

Send the response to a deferred ctrl command.

The command can only be a resply to a SET or a GET operation.

Parameters

  [in] | cd | deferred ctrl command state

Returns
  0 if command sent successfully; negative on error

References ctrl_cmd::ccon, ctrl_cmd_def::cmd, ctrl_cmd_send2(), CTRL_TYPE_ERROR, CTRL_TYPE_GET, CTRL_TYPE_GET_REPLY, CTRL_TYPE_SET, CTRL_TYPE_SET_REPLY, ctrl_cmd_def::list, llist_del(), and ctrl_cmd::type.

## ◆ ctrl_cmd_exec()

int ctrl_cmd_exec | ( | vector | vline,
|  | struct ctrl_cmd * | command,
|  | vector | node,
|  | void * | data
| ) |  |

Execute a given received command.

Parameters

  [in] | vline | vector representing the available/registered commands
  [in,out] | command | parsed received command to be executed
  [in] | node | CTRL interface node
  [in] | data | opaque data passed to verify(), get() and set() call-backs

Returns
  CTRL_CMD_HANDLED or CTRL_CMD_REPLY; CTRL_CMD_ERROR on error

References CTRL_CMD_ERROR, ctrl_cmd_get_element_match(), CTRL_CMD_REPLY, CTRL_TYPE_ERROR, CTRL_TYPE_GET, CTRL_TYPE_GET_REPLY, CTRL_TYPE_SET, CTRL_TYPE_SET_REPLY, data, ctrl_cmd_element::get, node, ctrl_cmd::reply, ctrl_cmd_element::set, ctrl_cmd::type, ctrl_cmd::value, and ctrl_cmd_element::verify.

Referenced by ctrl_cmd_handle().

## ◆ ctrl_cmd_get_element_match()

static struct ctrl_cmd_element * ctrl_cmd_get_element_match | ( | vector | vline,
|  | vector | node
| ) |  |
| static

References ctrl_cmd_struct::command, node, ctrl_cmd_struct::nr_commands, ctrl_cmd_element::strcmd, vector_active, and vector_slot.

Referenced by ctrl_cmd_exec().

## ◆ ctrl_cmd_install()

int ctrl_cmd_install | ( | enum ctrl_node_type | node,
|  | struct ctrl_cmd_element * | cmd
| ) |  |

Install a given command definition at a given CTRL node.

Parameters

  [in] | node | CTRL node at which cmd is to be installed
  [in] | cmd | command definition to be installed

Returns
  0 on success; negative on error

References create_cmd_struct(), ctrl_node_vec, DLCTRL, LOGL_ERROR, LOGP, ctrl_cmd_element::name, node, ctrl_cmd_element::strcmd, vector_init(), vector_lookup_ensure(), vector_set(), and vector_set_index().

Referenced by ctrl_init(), and osmo_fsm_ctrl_cmds_install().

## ◆ ctrl_cmd_make()

struct msgb * ctrl_cmd_make | ( | struct ctrl_cmd * | cmd | ) |

Encode a given CTRL command from its parsed form into a message buffer.

Parameters

  [in] | cmd | decoded/parsed form of to-be-encoded command

Returns
  callee-allocated message buffer containing the encoded cmd; NULL on error

References CTRL_TYPE_ERROR, CTRL_TYPE_GET, CTRL_TYPE_GET_REPLY, CTRL_TYPE_SET, CTRL_TYPE_SET_REPLY, CTRL_TYPE_TRAP, ctrl_type_vals, DLCTRL, get_value_string(), ctrl_cmd::id, len(), LOGL_ERROR, LOGL_NOTICE, LOGP, msg, msgb_alloc_headroom(), msgb_put(), ctrl_cmd::reply, type, ctrl_cmd::type, ctrl_cmd::value, and ctrl_cmd::variable.

Referenced by ctrl_cmd_send2().

## ◆ ctrl_cmd_parse()

struct ctrl_cmd * ctrl_cmd_parse | ( | void * | ctx,
|  | struct msgb * | msg
| ) |  |

Parse/Decode CTRL from Message buffers into command struct.

Parameters

  [in] | ctx | talloc context from which to allocate
  [in] | msg | message buffer containing command to be decoded

Returns
  callee-allocated decoded CTRL command; NULL on allocation or other failure The caller is responsible to talloc_free() the returned struct pointer.

References ctrl_cmd_parse2(), CTRL_TYPE_ERROR, msg, and res.

## ◆ ctrl_cmd_parse2()

struct ctrl_cmd * ctrl_cmd_parse2 | ( | void * | ctx,
|  | struct msgb * | msg
| ) |  |

Parse/Decode CTRL from Message buffers into command struct.

Parameters

  [in] | ctx | talloc context from which to allocate
  [in] | msg | message buffer containing command to be decoded

Returns
  callee-allocated decoded CTRL command; NULL on allocation failure, ctrl->type == CTRL_TYPE_ERROR and an error message in ctrl->reply on any error. The caller is responsible to talloc_free() the returned struct pointer. If information of the origin of the ERROR cmd returned is required (received or local parsing failure), use ctrl_cmd_parse3 instead.

References ctrl_cmd_parse3(), and msg.

Referenced by ctrl_cmd_exec_from_string(), and ctrl_cmd_parse().

## ◆ ctrl_cmd_parse3()

struct ctrl_cmd * ctrl_cmd_parse3 | ( | void * | ctx,
|  | struct msgb * | msg,
|  | bool * | parse_failed
| ) |  |

Parse/Decode CTRL from Message buffers into command struct.

Parameters

  [in] | ctx | talloc context from which to allocate
  [in] | msg | message buffer containing command to be decoded
  [out] | parse_failed | Whether returned ERROR cmd was generatd locally (due to parse failure) or was received.

Returns
  callee-allocated decoded CTRL command; NULL on allocation failure, ctrl->type == CTRL_TYPE_ERROR and an error message in ctrl->reply on any error. The caller is responsible to talloc_free() the returned struct pointer.

References CTRL_TYPE_ERROR, CTRL_TYPE_GET, CTRL_TYPE_GET_REPLY, CTRL_TYPE_SET, CTRL_TYPE_SET_REPLY, CTRL_TYPE_TRAP, CTRL_TYPE_UNKNOWN, ctrl_type_vals, DLCTRL, get_string_value(), get_value_string(), ctrl_cmd::id, id_str_valid(), LOGL_DEBUG, LOGL_ERROR, LOGL_NOTICE, LOGP, msg, msgb_put_u8(), OSMO_ASSERT, osmo_escape_str(), osmo_separated_identifiers_valid(), ctrl_cmd::reply, REPLY_CASE, ctrl_cmd::type, ctrl_cmd::value, and ctrl_cmd::variable.

Referenced by ctrl_cmd_parse2(), and ctrl_handle_msg().

## ◆ id_str_valid()

static bool id_str_valid | ( | const char * | str | ) |
| static

Referenced by ctrl_cmd_parse3().

## Variable Documentation

## ◆ ctrl_node_vec

vector ctrl_node_vec
| extern

Referenced by ctrl_cmd_handle(), ctrl_cmd_install(), and ctrl_init().

## ◆ ctrl_type_vals

const struct value_string ctrl_type_vals[]

Initial value:
= {
{ CTRL_TYPE_UNKNOWN, "(unknown)" },
{ CTRL_TYPE_GET, "GET" },
{ CTRL_TYPE_SET, "SET" },
{ CTRL_TYPE_GET_REPLY, "GET_REPLY" },
{ CTRL_TYPE_SET_REPLY, "SET_REPLY" },
{ CTRL_TYPE_TRAP, "TRAP" },
{ CTRL_TYPE_ERROR, "ERROR" },
{ 0, NULL }
}
CTRL_TYPE_GET_REPLY
@ CTRL_TYPE_GET_REPLY
Definition: control_cmd.h:36
CTRL_TYPE_SET_REPLY
@ CTRL_TYPE_SET_REPLY
Definition: control_cmd.h:37
CTRL_TYPE_SET
@ CTRL_TYPE_SET
Definition: control_cmd.h:35
CTRL_TYPE_GET
@ CTRL_TYPE_GET
Definition: control_cmd.h:34
CTRL_TYPE_UNKNOWN
@ CTRL_TYPE_UNKNOWN
Definition: control_cmd.h:33
CTRL_TYPE_TRAP
@ CTRL_TYPE_TRAP
Definition: control_cmd.h:38

human-readable string names for ctrl_type

Referenced by ctrl_cmd_handle(), ctrl_cmd_make(), ctrl_cmd_parse3(), and ctrl_handle_msg().