135c4b3e40ae905598f8444222c01b6fb1605f29
[dpdk.git] / 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