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 25extern "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() */ 40typedef int (*arg_handler_t)(const char *key, const char *value, void *opaque); 41 42/** A key/value association */ 43struct 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 */ 49struct 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 */ 73struct 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 102struct 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 */ 115void rte_kvargs_free(struct rte_kvargs *kvlist); 116 117/** 118 * Call a handler function for each key/value matching the key 119 * 120 * For each key/value association that matches the given key, calls the 121 * handler function with the for a given arg_name passing the value on the 122 * dictionary for that key and a given extra argument. 123 * 124 * @param kvlist 125 * The rte_kvargs structure. No error if NULL. 126 * @param key_match 127 * The key on which the handler should be called, or NULL to process handler 128 * on all associations 129 * @param handler 130 * The function to call for each matching key 131 * @param opaque_arg 132 * A pointer passed unchanged to the handler 133 * 134 * @return 135 * - 0 on success 136 * - Negative on error 137 */ 138int rte_kvargs_process(const struct rte_kvargs *kvlist, 139 const char *key_match, arg_handler_t handler, void *opaque_arg); 140 141/** 142 * Count the number of associations matching the given key 143 * 144 * @param kvlist 145 * The rte_kvargs structure 146 * @param key_match 147 * The key that should match, or NULL to count all associations 148 149 * @return 150 * The number of entries 151 */ 152unsigned rte_kvargs_count(const struct rte_kvargs *kvlist, 153 const char *key_match); 154 155/** 156 * Generic kvarg handler for string comparison. 157 * 158 * This function can be used for a generic string comparison processing 159 * on a list of kvargs. 160 * 161 * @param key 162 * kvarg pair key. 163 * 164 * @param value 165 * kvarg pair value. 166 * 167 * @param opaque 168 * Opaque pointer to a string. 169 * 170 * @return 171 * 0 if the strings match. 172 * !0 otherwise or on error. 173 * 174 * Unlike strcmp, comparison ordering is not kept. 175 * In order for rte_kvargs_process to stop processing on match error, 176 * a negative value is returned even if strcmp had returned a positive one. 177 */ 178__rte_experimental 179int rte_kvargs_strcmp(const char *key, const char *value, void *opaque); 180 181#ifdef __cplusplus 182} 183#endif 184 185#endif 186