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 /** Maximum number of key/value associations */ 29 #define RTE_KVARGS_MAX 32 30 31 /** separator character used between each pair */ 32 #define RTE_KVARGS_PAIRS_DELIM "," 33 34 /** separator character used between key and value */ 35 #define RTE_KVARGS_KV_DELIM "=" 36 37 /** 38 * Callback prototype used by rte_kvargs_process(). 39 * 40 * @param key 41 * The key to consider, it will not be NULL. 42 * @param value 43 * The value corresponding to the key, it may be NULL (e.g. only with key) 44 * @param opaque 45 * An opaque pointer coming from the caller. 46 * @return 47 * - >=0 handle key success. 48 * - <0 on error. 49 */ 50 typedef int (*arg_handler_t)(const char *key, const char *value, void *opaque); 51 52 /** A key/value association */ 53 struct rte_kvargs_pair { 54 char *key; /**< the name (key) of the association */ 55 char *value; /**< the value associated to that key */ 56 }; 57 58 /** Store a list of key/value associations */ 59 struct rte_kvargs { 60 char *str; /**< copy of the argument string */ 61 unsigned count; /**< number of entries in the list */ 62 struct rte_kvargs_pair pairs[RTE_KVARGS_MAX]; /**< list of key/values */ 63 }; 64 65 /** 66 * Allocate a rte_kvargs and store key/value associations from a string 67 * 68 * The function allocates and fills a rte_kvargs structure from a given 69 * string whose format is key1=value1,key2=value2,... 70 * 71 * The structure can be freed with rte_kvargs_free(). 72 * 73 * @param args 74 * The input string containing the key/value associations 75 * @param valid_keys 76 * A list of valid keys (table of const char *, the last must be NULL). 77 * This argument is ignored if NULL 78 * 79 * @return 80 * - A pointer to an allocated rte_kvargs structure on success 81 * - NULL on error 82 */ 83 struct rte_kvargs *rte_kvargs_parse(const char *args, 84 const char *const valid_keys[]); 85 86 /** 87 * Allocate a rte_kvargs and store key/value associations from a string. 88 * This version will consider any byte from valid_ends as a possible 89 * terminating character, and will not parse beyond any of their occurrence. 90 * 91 * The function allocates and fills an rte_kvargs structure from a given 92 * string whose format is key1=value1,key2=value2,... 93 * 94 * The structure can be freed with rte_kvargs_free(). 95 * 96 * @param args 97 * The input string containing the key/value associations 98 * 99 * @param valid_keys 100 * A list of valid keys (table of const char *, the last must be NULL). 101 * This argument is ignored if NULL 102 * 103 * @param valid_ends 104 * Acceptable terminating characters. 105 * If NULL, the behavior is the same as ``rte_kvargs_parse``. 106 * 107 * @return 108 * - A pointer to an allocated rte_kvargs structure on success 109 * - NULL on error 110 */ 111 struct rte_kvargs *rte_kvargs_parse_delim(const char *args, 112 const char *const valid_keys[], 113 const char *valid_ends); 114 115 /** 116 * Free a rte_kvargs structure 117 * 118 * Free a rte_kvargs structure previously allocated with 119 * rte_kvargs_parse(). 120 * 121 * @param kvlist 122 * The rte_kvargs structure. No error if NULL. 123 */ 124 void rte_kvargs_free(struct rte_kvargs *kvlist); 125 126 /** 127 * Get the value associated with a given key. 128 * 129 * If multiple keys match, the value of the first one is returned. 130 * 131 * The memory returned is allocated as part of the rte_kvargs structure, 132 * it must never be modified. 133 * 134 * @param kvlist 135 * A list of rte_kvargs pair of 'key=value'. 136 * @param key 137 * The matching key. 138 * 139 * @return 140 * NULL if no key matches the input, 141 * a value associated with a matching key otherwise. 142 */ 143 const char *rte_kvargs_get(const struct rte_kvargs *kvlist, const char *key); 144 145 /** 146 * Get the value associated with a given key and value. 147 * 148 * Find the first entry in the kvlist whose key and value match the 149 * ones passed as argument. 150 * 151 * The memory returned is allocated as part of the rte_kvargs structure, 152 * it must never be modified. 153 * 154 * @param kvlist 155 * A list of rte_kvargs pair of 'key=value'. 156 * @param key 157 * The matching key. If NULL, any key will match. 158 * @param value 159 * The matching value. If NULL, any value will match. 160 * 161 * @return 162 * NULL if no key matches the input, 163 * a value associated with a matching key otherwise. 164 */ 165 const char *rte_kvargs_get_with_value(const struct rte_kvargs *kvlist, 166 const char *key, const char *value); 167 168 /** 169 * Call a handler function for each key=value matching the key 170 * 171 * For each key=value association that matches the given key, calls the 172 * handler function with the for a given arg_name passing the value on the 173 * dictionary for that key and a given extra argument. 174 * 175 * @note Compared to @see rte_kvargs_process_opt, this API will return -1 176 * when handle only-key case (that is the matched key's value is NULL). 177 * 178 * @param kvlist 179 * The rte_kvargs structure. 180 * @param key_match 181 * The key on which the handler should be called, or NULL to process handler 182 * on all associations 183 * @param handler 184 * The function to call for each matching key 185 * @param opaque_arg 186 * A pointer passed unchanged to the handler 187 * 188 * @return 189 * - 0 on success 190 * - Negative on error 191 */ 192 int rte_kvargs_process(const struct rte_kvargs *kvlist, 193 const char *key_match, arg_handler_t handler, void *opaque_arg); 194 195 /** 196 * Call a handler function for each key=value or only-key matching the key 197 * 198 * For each key=value or only-key association that matches the given key, calls 199 * the handler function with the for a given arg_name passing the value on the 200 * dictionary for that key and a given extra argument. 201 * 202 * @param kvlist 203 * The rte_kvargs structure. 204 * @param key_match 205 * The key on which the handler should be called, or NULL to process handler 206 * on all associations 207 * @param handler 208 * The function to call for each matching key 209 * @param opaque_arg 210 * A pointer passed unchanged to the handler 211 * 212 * @return 213 * - 0 on success 214 * - Negative on error 215 */ 216 int rte_kvargs_process_opt(const struct rte_kvargs *kvlist, 217 const char *key_match, arg_handler_t handler, void *opaque_arg); 218 219 /** 220 * Count the number of associations matching the given key 221 * 222 * @param kvlist 223 * The rte_kvargs structure 224 * @param key_match 225 * The key that should match, or NULL to count all associations 226 * 227 * @return 228 * The number of entries 229 */ 230 unsigned rte_kvargs_count(const struct rte_kvargs *kvlist, 231 const char *key_match); 232 233 #ifdef __cplusplus 234 } 235 #endif 236 237 #endif 238