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 #ifdef __cplusplus 201 } 202 #endif 203 204 #endif 205