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 __rte_experimental 102 struct rte_kvargs *rte_kvargs_parse_delim(const char *args, 103 const char *const valid_keys[], 104 const char *valid_ends); 105 106 /** 107 * Free a rte_kvargs structure 108 * 109 * Free a rte_kvargs structure previously allocated with 110 * rte_kvargs_parse(). 111 * 112 * @param kvlist 113 * The rte_kvargs structure. No error if NULL. 114 */ 115 void rte_kvargs_free(struct rte_kvargs *kvlist); 116 117 /** 118 * Get the value associated with a given key. 119 * 120 * If multiple key matches, the value of the first one is returned. 121 * 122 * The memory returned is allocated as part of the rte_kvargs structure, 123 * it must never be modified. 124 * 125 * @param kvlist 126 * A list of rte_kvargs pair of 'key=value'. 127 * @param key 128 * The matching key. 129 130 * @return 131 * NULL if no key matches the input, 132 * a value associated with a matching key otherwise. 133 */ 134 __rte_experimental 135 const char *rte_kvargs_get(const struct rte_kvargs *kvlist, const char *key); 136 137 /** 138 * Call a handler function for each key/value matching the key 139 * 140 * For each key/value association that matches the given key, calls the 141 * handler function with the for a given arg_name passing the value on the 142 * dictionary for that key and a given extra argument. 143 * 144 * @param kvlist 145 * The rte_kvargs structure. No error if NULL. 146 * @param key_match 147 * The key on which the handler should be called, or NULL to process handler 148 * on all associations 149 * @param handler 150 * The function to call for each matching key 151 * @param opaque_arg 152 * A pointer passed unchanged to the handler 153 * 154 * @return 155 * - 0 on success 156 * - Negative on error 157 */ 158 int rte_kvargs_process(const struct rte_kvargs *kvlist, 159 const char *key_match, arg_handler_t handler, void *opaque_arg); 160 161 /** 162 * Count the number of associations matching the given key 163 * 164 * @param kvlist 165 * The rte_kvargs structure 166 * @param key_match 167 * The key that should match, or NULL to count all associations 168 169 * @return 170 * The number of entries 171 */ 172 unsigned rte_kvargs_count(const struct rte_kvargs *kvlist, 173 const char *key_match); 174 175 /** 176 * Generic kvarg handler for string comparison. 177 * 178 * This function can be used for a generic string comparison processing 179 * on a list of kvargs. 180 * 181 * @param key 182 * kvarg pair key. 183 * 184 * @param value 185 * kvarg pair value. 186 * 187 * @param opaque 188 * Opaque pointer to a string. 189 * 190 * @return 191 * 0 if the strings match. 192 * !0 otherwise or on error. 193 * 194 * Unlike strcmp, comparison ordering is not kept. 195 * In order for rte_kvargs_process to stop processing on match error, 196 * a negative value is returned even if strcmp had returned a positive one. 197 */ 198 __rte_experimental 199 int rte_kvargs_strcmp(const char *key, const char *value, void *opaque); 200 201 #ifdef __cplusplus 202 } 203 #endif 204 205 #endif 206