ae9ae79f21853780f23d1880581d7f26258ddaa4
[dpdk.git] / lib / librte_kvargs / rte_kvargs.h
1 /*-
2  *   BSD LICENSE
3  *
4  *   Copyright(c) 2010-2013 Intel Corporation. All rights reserved.
5  *   Copyright(c) 2014 6WIND S.A.
6  *   All rights reserved.
7  *
8  *   Redistribution and use in source and binary forms, with or without
9  *   modification, are permitted provided that the following conditions
10  *   are met:
11  *
12  *     * Redistributions of source code must retain the above copyright
13  *       notice, this list of conditions and the following disclaimer.
14  *     * Redistributions in binary form must reproduce the above copyright
15  *       notice, this list of conditions and the following disclaimer in
16  *       the documentation and/or other materials provided with the
17  *       distribution.
18  *     * Neither the name of Intel Corporation nor the names of its
19  *       contributors may be used to endorse or promote products derived
20  *       from this software without specific prior written permission.
21  *
22  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
25  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
26  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
27  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
28  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
29  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
30  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
32  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33  */
34
35 #ifndef _RTE_KVARGS_H_
36 #define _RTE_KVARGS_H_
37
38 /**
39  * @file
40  * RTE Argument parsing
41  *
42  * This module can be used to parse arguments whose format is
43  * key1=value1,key2=value2,key3=value3,...
44  *
45  * The same key can appear several times with the same or a different
46  * value. Indeed, the arguments are stored as a list of key/values
47  * associations and not as a dictionary.
48  *
49  * This file provides some helpers that are especially used by virtual
50  * ethernet devices at initialization for arguments parsing.
51  */
52
53 #ifdef __cplusplus
54 extern "C" {
55 #endif
56
57 /** Maximum number of key/value associations */
58 #define RTE_KVARGS_MAX 32
59
60 /** separator character used between each pair */
61 #define RTE_KVARGS_PAIRS_DELIM  ","
62
63 /** separator character used between key and value */
64 #define RTE_KVARGS_KV_DELIM     "="
65
66 /** Type of callback function used by rte_kvargs_process() */
67 typedef int (*arg_handler_t)(const char *key, const char *value, void *opaque);
68
69 /** A key/value association */
70 struct rte_kvargs_pair {
71         char *key;      /**< the name (key) of the association  */
72         char *value;    /**< the value associated to that key */
73 };
74
75 /** Store a list of key/value associations */
76 struct rte_kvargs {
77         char *str;      /**< copy of the argument string */
78         unsigned count; /**< number of entries in the list */
79         struct rte_kvargs_pair pairs[RTE_KVARGS_MAX]; /**< list of key/values */
80 };
81
82 /**
83  * Allocate a rte_kvargs and store key/value associations from a string
84  *
85  * The function allocates and fills a rte_kvargs structure from a given
86  * string whose format is key1=value1,key2=value2,...
87  *
88  * The structure can be freed with rte_kvargs_free().
89  *
90  * @param args
91  *   The input string containing the key/value associations
92  * @param valid_keys
93  *   A list of valid keys (table of const char *, the last must be NULL).
94  *   This argument is ignored if NULL
95  *
96  * @return
97  *   - A pointer to an allocated rte_kvargs structure on success
98  *   - NULL on error
99  */
100 struct rte_kvargs *rte_kvargs_parse(const char *args, const char *valid_keys[]);
101
102 /**
103  * Free a rte_kvargs structure
104  *
105  * Free a rte_kvargs structure previously allocated with
106  * rte_kvargs_parse().
107  *
108  * @param kvlist
109  *   The rte_kvargs structure
110  */
111 void rte_kvargs_free(struct rte_kvargs *kvlist);
112
113 /**
114  * Call a handler function for each key/value matching the key
115  *
116  * For each key/value association that matches the given key, calls the
117  * handler function with the for a given arg_name passing the value on the
118  * dictionary for that key and a given extra argument. If *kvlist* is NULL
119  * function does nothing.
120  *
121  * @param kvlist
122  *   The rte_kvargs structure
123  * @param key_match
124  *   The key on which the handler should be called, or NULL to process handler
125  *   on all associations
126  * @param handler
127  *   The function to call for each matching key
128  * @param opaque_arg
129  *   A pointer passed unchanged to the handler
130  *
131  * @return
132  *   - 0 on success
133  *   - Negative on error
134  */
135 int rte_kvargs_process(const struct rte_kvargs *kvlist,
136         const char *key_match, arg_handler_t handler, void *opaque_arg);
137
138 /**
139  * Count the number of associations matching the given key
140  *
141  * @param kvlist
142  *   The rte_kvargs structure
143  * @param key_match
144  *   The key that should match, or NULL to count all associations
145
146  * @return
147  *   The number of entries
148  */
149 unsigned rte_kvargs_count(const struct rte_kvargs *kvlist,
150         const char *key_match);
151
152 #ifdef __cplusplus
153 }
154 #endif
155
156 #endif