00001 // Copyright (C) 2006-2007 Benedikt Böhm <hollow@gentoo.org> 00002 // 00003 // This program is free software; you can redistribute it and/or 00004 // modify it under the terms of the GNU General Public License 00005 // as published by the Free Software Foundation; either version 2 00006 // of the License, or (at your option) any later version. 00007 // 00008 // This program is distributed in the hope that it will be useful, 00009 // but WITHOUT ANY WARRANTY; without even the implied warranty of 00010 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00011 // GNU General Public License for more details. 00012 // 00013 // You should have received a copy of the GNU General Public License 00014 // along with this program; if not, write to the Free Software 00015 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA 00016 00017 /*! 00018 * @defgroup flist Flag list conversion 00019 * 00020 * The flag list family of functions manages a list of possible values of a 00021 * bitmap using strings as key into the list. 00022 * 00023 * A bitmap is simply an integer with certain bits being 1 (enabled) and 0 00024 * (disabled). 00025 * 00026 * The FLIST32_START and FLIST64_START macros provides a shortcut for list 00027 * declaration and initialization; followed by one or more of FLIST32_NODE, 00028 * FLIST32_NODE1, FLIST64_NODE and FLIST64_NODE1 to insert nodes into the list. 00029 * The FLIST32_NODE1 and FLIST64_NODE1 macros are the same as FLIST32_NODE and 00030 * FLIST64_NODE, respectively, except that they convert the bit index to a 00031 * bitmap value before storing it in the list. The list should then be 00032 * terminated using FLIST32_END or FLIST64_END, respectively. 00033 * 00034 * The flist32_getval(), flist64_getval(), flist32_getkey() and flist64_getkey() 00035 * functions provide lookup routines by key and value, respectively. 00036 * 00037 * The flist32_from_str() and flist64_from_str() functions convert a string 00038 * consisting of zero or more flag list keys seperated by a delimiter and 00039 * optionally prefixed with a clear modifier to a bitmap/bitmask pair according 00040 * to a given list. 00041 * 00042 * The flist32_to_str() and flist64_to_str() functions convert a bitmap 00043 * according to a given list to a string consisting of zero or more flag list 00044 * keys seperated by a delimiter. 00045 * 00046 * @{ 00047 */ 00048 00049 #ifndef _LUCID_FLIST_H 00050 #define _LUCID_FLIST_H 00051 00052 #include <stdint.h> 00053 00054 /*! @brief 32 bit list object */ 00055 typedef struct { 00056 const char *key; /*!< Node key (must be unique) */ 00057 const uint32_t val; /*!< Node value (32-bit) */ 00058 } flist32_t; 00059 00060 /*! @brief 32 bit list initialization */ 00061 #define FLIST32_START(LIST) const flist32_t LIST[] = { 00062 00063 /*! @brief 32 bit list node */ 00064 #define FLIST32_NODE(PREFIX, NAME) { #NAME, PREFIX ## _ ## NAME }, 00065 00066 /*! @brief 32 bit list node from index */ 00067 #define FLIST32_NODE1(PREFIX, NAME) { #NAME, (1 << PREFIX ## _ ## NAME) }, 00068 00069 /*! @brief 32 bit list termination */ 00070 #define FLIST32_END { 0, 0 } }; 00071 00072 /*! 00073 * @brief get 32 bit value by key 00074 * 00075 * @param[in] list list to use for conversion 00076 * @param[in] key key to look for 00077 * 00078 * @return 32 bit value >= 1 if key found, 0 otherwise 00079 */ 00080 uint32_t flist32_getval(const flist32_t list[], const char *key); 00081 00082 /*! 00083 * @brief get key from 32 bit value 00084 * 00085 * @param[in] list list to use for conversion 00086 * @param[in] val 32 bit key to look for 00087 * 00088 * @return key if value was found, NULL otherwise 00089 * 00090 * @note this functions does not reset the flags or mask argument to an empty 00091 * bitmap, thus allowing incremental changes to the map. 00092 */ 00093 const char *flist32_getkey(const flist32_t list[], uint32_t val); 00094 00095 /*! 00096 * @brief parse flag list string 00097 * 00098 * @param[in] str string to convert 00099 * @param[in] list list to use for conversion 00100 * @param[out] flags pointer to a bit mask 00101 * @param[out] mask pointer to a set mask 00102 * @param[in] clmod clear flag modifier 00103 * @param[in] delim flag delimiter 00104 * 00105 * @return 0 on success, -1 on error with errno set 00106 */ 00107 int flist32_from_str(const char *str, const flist32_t list[], 00108 uint32_t *flags, uint32_t *mask, 00109 char clmod, char *delim); 00110 00111 /*! 00112 * @brief convert bit mask to flag list string 00113 * 00114 * @param[in] list list to use for conversion 00115 * @param[in] val bit mask 00116 * @param[in] delim flag delimiter 00117 * 00118 * @return flags list string 00119 * 00120 * @note this function ignores set bits if they do not appear in the list 00121 * @note if no flag was found or the bitmap was empty, an empty string is 00122 * returned, not NULL 00123 */ 00124 char *flist32_to_str(const flist32_t list[], uint32_t val, char *delim); 00125 00126 00127 00128 /*! @brief 64 bit list object */ 00129 typedef struct { 00130 const char *key; /*!< Node key (must be unique) */ 00131 const uint64_t val; /*!< Node value (64-bit) */ 00132 } flist64_t; 00133 00134 /*! @brief 64 bit list initialization */ 00135 #define FLIST64_START(LIST) const flist64_t LIST[] = { 00136 00137 /*! @brief 64 bit list node */ 00138 #define FLIST64_NODE(PREFIX, NAME) { #NAME, PREFIX ## _ ## NAME }, 00139 00140 /*! @brief 64 bit list node from index */ 00141 #define FLIST64_NODE1(PREFIX, NAME) { #NAME, (1 << PREFIX ## _ ## NAME) }, 00142 00143 /*! @brief 64 bit list termination */ 00144 #define FLIST64_END { 0, 0 } }; 00145 00146 /*! 00147 * @brief get 64 bit value by key 00148 * 00149 * @param[in] list list to use for conversion 00150 * @param[in] key key to look for 00151 * 00152 * @return 64 bit value >= 1 if key was found, 0 otherwise 00153 */ 00154 uint64_t flist64_getval(const flist64_t list[], const char *key); 00155 00156 /*! 00157 * @brief get key from 64 bit value 00158 * 00159 * @param[in] list list to use for conversion 00160 * @param[in] val 64 bit key to look for 00161 * 00162 * @return key if value was found, NULL otherwise 00163 */ 00164 const char *flist64_getkey(const flist64_t list[], uint64_t val); 00165 00166 /*! 00167 * @brief parse flag list string 00168 * 00169 * @param[in] str string to convert 00170 * @param[in] list list to use for conversion 00171 * @param[out] flags pointer to a bit mask 00172 * @param[out] mask pointer to a set mask 00173 * @param[in] clmod clear flag modifier 00174 * @param[in] delim flag delimiter 00175 * 00176 * @return 0 on success, -1 on error with errno set 00177 * 00178 * @note this functions does not reset the flags or mask argument to an empty 00179 * bitmap, thus allowing incremental changes to the map. 00180 */ 00181 int flist64_from_str(const char *str, const flist64_t list[], 00182 uint64_t *flags, uint64_t *mask, 00183 char clmod, char *delim); 00184 00185 /*! 00186 * @brief convert bit mask to flag list string 00187 * 00188 * @param[in] list list to use for conversion 00189 * @param[in] val bit mask 00190 * @param[in] delim flag delimiter 00191 * 00192 * @return flags list string 00193 * 00194 * @note this function ignores set bits if they do not appear in the list 00195 * @note if no flag was found or the bitmap was empty, an empty string is 00196 * returned, not NULL 00197 */ 00198 char *flist64_to_str(const flist64_t list[], uint64_t val, char *delim); 00199 00200 #endif 00201 00202 /*! @} flist */