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