lib/kvargs/rte_kvargs.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2010-2013 Intel Corporation.
   3  * Copyright(c) 2014 6WIND S.A.
   4  */
   5
   6 #ifndef _RTE_KVARGS_H_
   7 #define _RTE_KVARGS_H_
   8
   9 /**
  10  * @file
  11  * RTE Argument parsing
  12  *
  13  * This module can be used to parse arguments whose format is
  14  * key1=value1,key2=value2,key3=value3,...
  15  *
  16  * The same key can appear several times with the same or a different
  17  * value. Indeed, the arguments are stored as a list of key/values
  18  * associations and not as a dictionary.
  19  *
  20  * This file provides some helpers that are especially used by virtual
  21  * ethernet devices at initialization for arguments parsing.
  22  */
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 #include <rte_compat.h>
  29
  30 /** Maximum number of key/value associations */
  31 #define RTE_KVARGS_MAX 32
  32
  33 /** separator character used between each pair */
  34 #define RTE_KVARGS_PAIRS_DELIM  ","
  35
  36 /** separator character used between key and value */
  37 #define RTE_KVARGS_KV_DELIM     "="
  38
  39 /** Type of callback function used by rte_kvargs_process() */
  40 typedef int (*arg_handler_t)(const char *key, const char *value, void *opaque);
  41
  42 /** A key/value association */
  43 struct rte_kvargs_pair {
  44         char *key;      /**< the name (key) of the association  */
  45         char *value;    /**< the value associated to that key */
  46 };
  47
  48 /** Store a list of key/value associations */
  49 struct rte_kvargs {
  50         char *str;      /**< copy of the argument string */
  51         unsigned count; /**< number of entries in the list */
  52         struct rte_kvargs_pair pairs[RTE_KVARGS_MAX]; /**< list of key/values */
  53 };
  54
  55 /**
  56  * Allocate a rte_kvargs and store key/value associations from a string
  57  *
  58  * The function allocates and fills a rte_kvargs structure from a given
  59  * string whose format is key1=value1,key2=value2,...
  60  *
  61  * The structure can be freed with rte_kvargs_free().
  62  *
  63  * @param args
  64  *   The input string containing the key/value associations
  65  * @param valid_keys
  66  *   A list of valid keys (table of const char *, the last must be NULL).
  67  *   This argument is ignored if NULL
  68  *
  69  * @return
  70  *   - A pointer to an allocated rte_kvargs structure on success
  71  *   - NULL on error
  72  */
  73 struct rte_kvargs *rte_kvargs_parse(const char *args,
  74                 const char *const valid_keys[]);
  75
  76 /**
  77  * Allocate a rte_kvargs and store key/value associations from a string.
  78  * This version will consider any byte from valid_ends as a possible
  79  * terminating character, and will not parse beyond any of their occurrence.
  80  *
  81  * The function allocates and fills an rte_kvargs structure from a given
  82  * string whose format is key1=value1,key2=value2,...
  83  *
  84  * The structure can be freed with rte_kvargs_free().
  85  *
  86  * @param args
  87  *   The input string containing the key/value associations
  88  *
  89  * @param valid_keys
  90  *   A list of valid keys (table of const char *, the last must be NULL).
  91  *   This argument is ignored if NULL
  92  *
  93  * @param valid_ends
  94  *   Acceptable terminating characters.
  95  *   If NULL, the behavior is the same as ``rte_kvargs_parse``.
  96  *
  97  * @return
  98  *   - A pointer to an allocated rte_kvargs structure on success
  99  *   - NULL on error
 100  */
 101 struct rte_kvargs *rte_kvargs_parse_delim(const char *args,
 102                 const char *const valid_keys[],
 103                 const char *valid_ends);
 104
 105 /**
 106  * Free a rte_kvargs structure
 107  *
 108  * Free a rte_kvargs structure previously allocated with
 109  * rte_kvargs_parse().
 110  *
 111  * @param kvlist
 112  *   The rte_kvargs structure. No error if NULL.
 113  */
 114 void rte_kvargs_free(struct rte_kvargs *kvlist);
 115
 116 /**
 117  * Get the value associated with a given key.
 118  *
 119  * If multiple keys match, the value of the first one is returned.
 120  *
 121  * The memory returned is allocated as part of the rte_kvargs structure,
 122  * it must never be modified.
 123  *
 124  * @param kvlist
 125  *   A list of rte_kvargs pair of 'key=value'.
 126  * @param key
 127  *   The matching key.
 128  *
 129  * @return
 130  *   NULL if no key matches the input,
 131  *   a value associated with a matching key otherwise.
 132  */
 133 const char *rte_kvargs_get(const struct rte_kvargs *kvlist, const char *key);
 134
 135 /**
 136  * @warning
 137  * @b EXPERIMENTAL: this API may change without prior notice
 138  *
 139  * Get the value associated with a given key and value.
 140  *
 141  * Find the first entry in the kvlist whose key and value match the
 142  * ones passed as argument.
 143  *
 144  * The memory returned is allocated as part of the rte_kvargs structure,
 145  * it must never be modified.
 146  *
 147  * @param kvlist
 148  *   A list of rte_kvargs pair of 'key=value'.
 149  * @param key
 150  *   The matching key. If NULL, any key will match.
 151  * @param value
 152  *   The matching value. If NULL, any value will match.
 153  *
 154  * @return
 155  *   NULL if no key matches the input,
 156  *   a value associated with a matching key otherwise.
 157  */
 158 __rte_experimental
 159 const char *rte_kvargs_get_with_value(const struct rte_kvargs *kvlist,
 160                                       const char *key, const char *value);
 161
 162 /**
 163  * Call a handler function for each key/value matching the key
 164  *
 165  * For each key/value association that matches the given key, calls the
 166  * handler function with the for a given arg_name passing the value on the
 167  * dictionary for that key and a given extra argument.
 168  *
 169  * @param kvlist
 170  *   The rte_kvargs structure. No error if NULL.
 171  * @param key_match
 172  *   The key on which the handler should be called, or NULL to process handler
 173  *   on all associations
 174  * @param handler
 175  *   The function to call for each matching key
 176  * @param opaque_arg
 177  *   A pointer passed unchanged to the handler
 178  *
 179  * @return
 180  *   - 0 on success
 181  *   - Negative on error
 182  */
 183 int rte_kvargs_process(const struct rte_kvargs *kvlist,
 184         const char *key_match, arg_handler_t handler, void *opaque_arg);
 185
 186 /**
 187  * Count the number of associations matching the given key
 188  *
 189  * @param kvlist
 190  *   The rte_kvargs structure
 191  * @param key_match
 192  *   The key that should match, or NULL to count all associations
 193  *
 194  * @return
 195  *   The number of entries
 196  */
 197 unsigned rte_kvargs_count(const struct rte_kvargs *kvlist,
 198         const char *key_match);
 199
 200 /**
 201  * Generic kvarg handler for string comparison.
 202  *
 203  * This function can be used for a generic string comparison processing
 204  * on a list of kvargs.
 205  *
 206  * @param key
 207  *   kvarg pair key.
 208  *
 209  * @param value
 210  *   kvarg pair value.
 211  *
 212  * @param opaque
 213  *   Opaque pointer to a string.
 214  *
 215  * @return
 216  *   0 if the strings match.
 217  *   !0 otherwise or on error.
 218  *
 219  *   Unlike strcmp, comparison ordering is not kept.
 220  *   In order for rte_kvargs_process to stop processing on match error,
 221  *   a negative value is returned even if strcmp had returned a positive one.
 222  */
 223 __rte_experimental
 224 int rte_kvargs_strcmp(const char *key, const char *value, void *opaque);
 225
 226 #ifdef __cplusplus
 227 }
 228 #endif
 229
 230 #endif