---
name: "rte_kvargs.h"
section: "3"
platform: "linux"
package: "dpdk-doc"
version: "24.11.4-0+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/rte_kvargs.h"
---

# rte\_kvargs.h(3)

## NAME

rte\_kvargs.h

## SYNOPSIS

### 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

This module can be used to parse arguments whose format is key1=value1,key2=value2,key3=value3,...

The same key can appear several times with the same or a different value. Indeed, the arguments are stored as a list of key/values associations and not as a dictionary.

This file provides some helpers that are especially used by virtual ethernet devices at initialization for arguments parsing.

Definition in file **rte\_kvargs.h**.

## Macro Definition Documentation

### #define RTE\_KVARGS\_MAX 32

Maximum number of key/value associations

Definition at line **29** of file **rte\_kvargs.h**.

### #define RTE\_KVARGS\_PAIRS\_DELIM ','

separator character used between each pair

Definition at line **32** of file **rte\_kvargs.h**.

### #define RTE\_KVARGS\_KV\_DELIM '='

separator character used between key and value

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()**.

**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()**.

**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.

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.

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).

**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.

**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.