lib/librte_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 /** Maximum number of key/value associations */
  29 #define RTE_KVARGS_MAX 32
  30
  31 /** separator character used between each pair */
  32 #define RTE_KVARGS_PAIRS_DELIM  ","
  33
  34 /** separator character used between key and value */
  35 #define RTE_KVARGS_KV_DELIM     "="
  36
  37 /** Type of callback function used by rte_kvargs_process() */
  38 typedef int (*arg_handler_t)(const char *key, const char *value, void *opaque);
  39
  40 /** A key/value association */
  41 struct rte_kvargs_pair {
  42         char *key;      /**< the name (key) of the association  */
  43         char *value;    /**< the value associated to that key */
  44 };
  45
  46 /** Store a list of key/value associations */
  47 struct rte_kvargs {
  48         char *str;      /**< copy of the argument string */
  49         unsigned count; /**< number of entries in the list */
  50         struct rte_kvargs_pair pairs[RTE_KVARGS_MAX]; /**< list of key/values */
  51 };
  52
  53 /**
  54  * Allocate a rte_kvargs and store key/value associations from a string
  55  *
  56  * The function allocates and fills a rte_kvargs structure from a given
  57  * string whose format is key1=value1,key2=value2,...
  58  *
  59  * The structure can be freed with rte_kvargs_free().
  60  *
  61  * @param args
  62  *   The input string containing the key/value associations
  63  * @param valid_keys
  64  *   A list of valid keys (table of const char *, the last must be NULL).
  65  *   This argument is ignored if NULL
  66  *
  67  * @return
  68  *   - A pointer to an allocated rte_kvargs structure on success
  69  *   - NULL on error
  70  */
  71 struct rte_kvargs *rte_kvargs_parse(const char *args,
  72                 const char *const valid_keys[]);
  73
  74 /**
  75  * Free a rte_kvargs structure
  76  *
  77  * Free a rte_kvargs structure previously allocated with
  78  * rte_kvargs_parse().
  79  *
  80  * @param kvlist
  81  *   The rte_kvargs structure
  82  */
  83 void rte_kvargs_free(struct rte_kvargs *kvlist);
  84
  85 /**
  86  * Call a handler function for each key/value matching the key
  87  *
  88  * For each key/value association that matches the given key, calls the
  89  * handler function with the for a given arg_name passing the value on the
  90  * dictionary for that key and a given extra argument. If *kvlist* is NULL
  91  * function does nothing.
  92  *
  93  * @param kvlist
  94  *   The rte_kvargs structure
  95  * @param key_match
  96  *   The key on which the handler should be called, or NULL to process handler
  97  *   on all associations
  98  * @param handler
  99  *   The function to call for each matching key
 100  * @param opaque_arg
 101  *   A pointer passed unchanged to the handler
 102  *
 103  * @return
 104  *   - 0 on success
 105  *   - Negative on error
 106  */
 107 int rte_kvargs_process(const struct rte_kvargs *kvlist,
 108         const char *key_match, arg_handler_t handler, void *opaque_arg);
 109
 110 /**
 111  * Count the number of associations matching the given key
 112  *
 113  * @param kvlist
 114  *   The rte_kvargs structure
 115  * @param key_match
 116  *   The key that should match, or NULL to count all associations
 117
 118  * @return
 119  *   The number of entries
 120  */
 121 unsigned rte_kvargs_count(const struct rte_kvargs *kvlist,
 122         const char *key_match);
 123
 124 #ifdef __cplusplus
 125 }
 126 #endif
 127
 128 #endif