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, 101 const char *const valid_keys[]); 102 103 /** 104 * Free a rte_kvargs structure 105 * 106 * Free a rte_kvargs structure previously allocated with 107 * rte_kvargs_parse(). 108 * 109 * @param kvlist 110 * The rte_kvargs structure 111 */ 112 void rte_kvargs_free(struct rte_kvargs *kvlist); 113 114 /** 115 * Call a handler function for each key/value matching the key 116 * 117 * For each key/value association that matches the given key, calls the 118 * handler function with the for a given arg_name passing the value on the 119 * dictionary for that key and a given extra argument. If *kvlist* is NULL 120 * function does nothing. 121 * 122 * @param kvlist 123 * The rte_kvargs structure 124 * @param key_match 125 * The key on which the handler should be called, or NULL to process handler 126 * on all associations 127 * @param handler 128 * The function to call for each matching key 129 * @param opaque_arg 130 * A pointer passed unchanged to the handler 131 * 132 * @return 133 * - 0 on success 134 * - Negative on error 135 */ 136 int rte_kvargs_process(const struct rte_kvargs *kvlist, 137 const char *key_match, arg_handler_t handler, void *opaque_arg); 138 139 /** 140 * Count the number of associations matching the given key 141 * 142 * @param kvlist 143 * The rte_kvargs structure 144 * @param key_match 145 * The key that should match, or NULL to count all associations 146 147 * @return 148 * The number of entries 149 */ 150 unsigned rte_kvargs_count(const struct rte_kvargs *kvlist, 151 const char *key_match); 152 153 #ifdef __cplusplus 154 } 155 #endif 156 157 #endif 158