rte_kvargs.h(3)

📦
version 25.11.3 · 11 versions
, in ubuntu resolute, ubuntu stonking

💖 rte_kvargs.h — the DPDK argument-parsing bestie 💖

okay so bestie, welcome to rte_kvargs.h, a manual page from the DPDK family (that's a Library Functions Manual, the cultured kind). This little file is the group chat where your key1=value1,key2=value2,... strings come to get sorted out. Let's get into it, no cap. ✨

🌸 SYNOPSIS 🌸

Here's everything this file hands you, bestie. Skim it, screenshot it, whatever.

🎀 Data Structures

  • struct rte_kvargs_pair
  • struct rte_kvargs

🎀 Macros

  • #define RTE_KVARGS_MAX 32
  • #define RTE_KVARGS_PAIRS_DELIM ','
  • #define RTE_KVARGS_KV_DELIM '='

🎀 Typedefs

typedef int(*arg_handler_t) (const char *key, const char *value, void *opaque)

🎀 Functions

struct rte_kvargs * rte_kvargs_parse (const char *args, const char
    *const valid_keys[])
struct rte_kvargs * rte_kvargs_parse_delim (const char *args, const char
    *const valid_keys[], const char *valid_ends)
void rte_kvargs_free (struct rte_kvargs *kvlist)
const char * rte_kvargs_get (const struct rte_kvargs *kvlist, const char
    *key)
const char * rte_kvargs_get_with_value (const struct rte_kvargs *kvlist,
    const char *key, const char *value)
int rte_kvargs_process (const struct rte_kvargs *kvlist, const char
    *key_match, arg_handler_t handler, void *opaque_arg)
int rte_kvargs_process_opt (const struct rte_kvargs *kvlist, const char
    *key_match, arg_handler_t handler, void *opaque_arg)
unsigned rte_kvargs_count (const struct rte_kvargs *kvlist, const char
    *key_match)

✨ Detailed Description ✨

RTE Argument parsing — that's the whole vibe. This module parses arguments shaped like:

key1=value1,key2=value2,key3=value3,...

and here's the tea 👑: the same key can show up several times, with the same value or a different one. That's because these arguments are stored as a list of key/value associations, not as a dictionary. Very "my notes app has the same reminder five times" of it.

This file also provides some helpers that get used especially by virtual ethernet devices at initialization, for arguments parsing. iykyk. 🦋

Definition in file rte_kvargs.h.

🧚 Macro Definition Documentation 🧚

#define RTE_KVARGS_MAX 32

Maximum number of key/value associations. That's your cap, bestie — 32, periodt.

Definition at line 29 of file rte_kvargs.h.

#define RTE_KVARGS_PAIRS_DELIM ','

separator character used between each pair. It's the comma doing cardio between your pairs. 🏃♀️

Definition at line 32 of file rte_kvargs.h.

#define RTE_KVARGS_KV_DELIM '='

separator character used between key and value. The = is the little bridge, iconic, no notes. 🌈

Definition at line 35 of file rte_kvargs.h.

💅 Typedef Documentation 💅

typedef int(*arg_handler_t) (const char *key, const char *value, void *opaque)

Callback prototype used by rte_kvargs_process(). So when that function is like "hey, I found a match", this is the shape of the function it calls back. 💖

Parameters

  • key — The key to consider, it will not be NULL.
  • value — The value corresponding to the key, it may be NULL (e.g. only with key).
  • opaque — An opaque pointer coming from the caller.

Returns

  • >=0 handle key success.
  • <0 on error.
Definition at line 50 of file rte_kvargs.h.

🔥 Function Documentation 🔥

struct rte_kvargs * rte_kvargs_parse (const char * args, const char *const valid_keys[])

Allocate a rte_kvargs and store key/value associations from a string.

The function allocates and fills a rte_kvargs structure from a given string whose format is key1=value1,key2=value2,....

The structure can be freed with rte_kvargs_free(). (Yes bestie, you gotta free it. 🫶)

Parameters

  • args — The input string containing the key/value associations.
  • valid_keys — A list of valid keys (table of const char *, the last must be NULL). This argument is ignored if NULL.

Returns

  • A pointer to an allocated rte_kvargs structure on success.
  • NULL on error.

struct rte_kvargs * rte_kvargs_parse_delim (const char * args, const char *const valid_keys[], const char * valid_ends)

Allocate a rte_kvargs and store key/value associations from a string. This version will consider any byte from valid_ends as a possible terminating character, and will not parse beyond any of their occurrence. Like a bouncer at the door of your string. 🚪

The function allocates and fills an rte_kvargs structure from a given string whose format is key1=value1,key2=value2,....

The structure can be freed with rte_kvargs_free().

Parameters

  • args — The input string containing the key/value associations.
  • valid_keys — A list of valid keys (table of const char *, the last must be NULL). This argument is ignored if NULL.
  • valid_ends — Acceptable terminating characters. If NULL, the behavior is the same as rte_kvargs_parse.

Returns

  • A pointer to an allocated rte_kvargs structure on success.
  • NULL on error.

void rte_kvargs_free (struct rte_kvargs * kvlist)

Free a rte_kvargs structure.

Free a rte_kvargs structure previously allocated with rte_kvargs_parse().

Parameters

  • kvlist — The rte_kvargs structure. No error if NULL.

const char * rte_kvargs_get (const struct rte_kvargs * kvlist, const char * key)

Get the value associated with a given key.

If multiple keys match, the value of the first one is returned. First come, first served, bestie. 💅

The memory returned is allocated as part of the rte_kvargs structure, it must never be modified.

Parameters

  • kvlist — A list of rte_kvargs pair of 'key=value'.
  • key — The matching key.

Returns

  • NULL if no key matches the input, a value associated with a matching key otherwise.

const char * rte_kvargs_get_with_value (const struct rte_kvargs * kvlist, const char * key, const char * value)

Get the value associated with a given key and value.

Find the first entry in the kvlist whose key and value match the ones passed as argument.

The memory returned is allocated as part of the rte_kvargs structure, it must never be modified.

Parameters

  • kvlist — A list of rte_kvargs pair of 'key=value'.
  • key — The matching key. If NULL, any key will match.
  • value — The matching value. If NULL, any value will match.

Returns

  • NULL if no key matches the input, a value associated with a matching key otherwise.

int rte_kvargs_process (const struct rte_kvargs * kvlist, const char * key_match, arg_handler_t handler, void * opaque_arg)

Call a handler function for each key=value matching the key.

For each key=value association that matches the given key, calls the handler function with the for a given arg_name passing the value on the dictionary for that key and a given extra argument.

Note: Compared to

See also: rte_kvargs_process_opt, this API will return -1 when handle only-key case (that is the matched key's value is NULL). 😭 so watch out for that one.

Parameters

  • kvlist — The rte_kvargs structure.
  • key_match — The key on which the handler should be called, or NULL to process handler on all associations.
  • handler — The function to call for each matching key.
  • opaque_arg — A pointer passed unchanged to the handler.

Returns

  • 0 on success.
  • Negative on error.

int rte_kvargs_process_opt (const struct rte_kvargs * kvlist, const char * key_match, arg_handler_t handler, void * opaque_arg)

Call a handler function for each key=value or only-key matching the key.

For each key=value or only-key association that matches the given key, calls the handler function with the for a given arg_name passing the value on the dictionary for that key and a given extra argument. This is the lenient one — it handles the only-key case too. 🍓

Parameters

  • kvlist — The rte_kvargs structure.
  • key_match — The key on which the handler should be called, or NULL to process handler on all associations.
  • handler — The function to call for each matching key.
  • opaque_arg — A pointer passed unchanged to the handler.

Returns

  • 0 on success.
  • Negative on error.

unsigned rte_kvargs_count (const struct rte_kvargs * kvlist, const char * key_match)

Count the number of associations matching the given key.

Parameters

  • kvlist — The rte_kvargs structure.
  • key_match — The key that should match, or NULL to count all associations.

Returns

  • The number of entries.

🦋 Author 🦋

Generated automatically by Doxygen for DPDK from the source code. (Not a human author, it's giving "authored by a very diligent robot" 🤖✨)

and that's the whole page bestie, you ate that. this was DPDK, Version 25.11.3, and the page itself is rte_kvargs.h(3). go forth and parse responsibly 💖🎀🌸

📦 where this page comes from