|
1 | 1 | /* |
2 | 2 | * Copyright © 2009 CNRS |
3 | | - * Copyright © 2009-2023 Inria. All rights reserved. |
| 3 | + * Copyright © 2009-2024 Inria. All rights reserved. |
4 | 4 | * Copyright © 2009-2012 Université Bordeaux |
5 | 5 | * Copyright © 2009-2011 Cisco Systems, Inc. All rights reserved. |
6 | 6 | * See COPYING in top-level directory. |
@@ -113,77 +113,132 @@ HWLOC_DECLSPEC int hwloc_bitmap_copy(hwloc_bitmap_t dst, hwloc_const_bitmap_t sr |
113 | 113 | * Bitmap/String Conversion |
114 | 114 | */ |
115 | 115 |
|
116 | | -/** \brief Stringify a bitmap. |
| 116 | +/** \brief Stringify a bitmap in the default hwloc format. |
| 117 | + * |
| 118 | + * <b>Note that if the bitmap is a CPU or nodeset, it contains physical indexes.</b> |
| 119 | + * |
| 120 | + * Print the bits set inside a bitmap as a comma-separated list of hexadecimal 32-bit blocks. |
| 121 | + * A bitmap containing bits 1, 33, 34, and all from 64 to 95 is printed as <tt>"0xffffffff,0x00000006,0x00000002"</tt>. |
117 | 122 | * |
118 | 123 | * Up to \p buflen characters may be written in buffer \p buf. |
119 | 124 | * |
120 | 125 | * If \p buflen is 0, \p buf may safely be \c NULL. |
121 | 126 | * |
122 | 127 | * \return the number of characters that were actually written if not truncating, |
123 | | - * or that would have been written (not including the ending \\0). |
| 128 | + * or that would have been written (not including the ending \c \0). |
| 129 | + * \return -1 on error. |
124 | 130 | */ |
125 | 131 | HWLOC_DECLSPEC int hwloc_bitmap_snprintf(char * __hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap); |
126 | 132 |
|
127 | | -/** \brief Stringify a bitmap into a newly allocated string. |
| 133 | +/** \brief Stringify a bitmap into a newly allocated string in the default hwloc format. |
128 | 134 | * |
129 | | - * \return 0 on success, -1 on error. |
| 135 | + * <b>Note that if the bitmap is a CPU or nodeset, it contains physical indexes.</b> |
| 136 | + * |
| 137 | + * Print the bits set inside a bitmap as a comma-separated list of hexadecimal 32-bit blocks. |
| 138 | + * A bitmap containing bits 1, 33, 34, and all from 64 to 95 is printed as <tt>"0xffffffff,0x00000006,0x00000002"</tt>. |
| 139 | + * |
| 140 | + * \return the number of characters that were written (not including the ending \c \0). |
| 141 | + * \return -1 on error, for instance with \p errno set to \c ENOMEM on failure to allocate the output string. |
130 | 142 | */ |
131 | 143 | HWLOC_DECLSPEC int hwloc_bitmap_asprintf(char ** strp, hwloc_const_bitmap_t bitmap); |
132 | 144 |
|
133 | | -/** \brief Parse a bitmap string and stores it in bitmap \p bitmap. |
| 145 | +/** \brief Parse a bitmap string as the default hwloc format and stores it in bitmap \p bitmap. |
| 146 | + * |
| 147 | + * <b>Note that if the bitmap is a CPU or nodeset, the input string must contain physical indexes.</b> |
| 148 | + * |
| 149 | + * The input string should be a comma-separared list of hexadecimal 32-bit blocks. |
| 150 | + * String <tt>"0xffffffff,0x6,0x2"</tt> is parsed as a bitmap containing all bits between 64 and 95, |
| 151 | + * and bits 33, 34 and 1. |
134 | 152 | * |
135 | 153 | * \return 0 on success, -1 on error. |
136 | 154 | */ |
137 | 155 | HWLOC_DECLSPEC int hwloc_bitmap_sscanf(hwloc_bitmap_t bitmap, const char * __hwloc_restrict string); |
138 | 156 |
|
139 | 157 | /** \brief Stringify a bitmap in the list format. |
| 158 | + * |
| 159 | + * <b>Note that if the bitmap is a CPU or nodeset, it contains physical indexes.</b> |
140 | 160 | * |
141 | 161 | * Lists are comma-separated indexes or ranges. |
142 | 162 | * Ranges are dash separated indexes. |
143 | | - * The last range may not have an ending indexes if the bitmap is infinitely set. |
| 163 | + * A bitmap containing bits 1, 33, 34, and all from 64 to 95 is printed as <tt>"1,33-34,64-95"</tt>. |
| 164 | + * The last range may not have an ending index if the bitmap is infinitely set. |
144 | 165 | * |
145 | 166 | * Up to \p buflen characters may be written in buffer \p buf. |
146 | 167 | * |
147 | 168 | * If \p buflen is 0, \p buf may safely be \c NULL. |
148 | 169 | * |
149 | 170 | * \return the number of characters that were actually written if not truncating, |
150 | | - * or that would have been written (not including the ending \\0). |
| 171 | + * or that would have been written (not including the ending \c \0). |
| 172 | + * \return -1 on error. |
151 | 173 | */ |
152 | 174 | HWLOC_DECLSPEC int hwloc_bitmap_list_snprintf(char * __hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap); |
153 | 175 |
|
154 | 176 | /** \brief Stringify a bitmap into a newly allocated list string. |
155 | 177 | * |
156 | | - * \return 0 on success, -1 on error. |
| 178 | + * <b>Note that if the bitmap is a CPU or nodeset, it contains physical indexes.</b> |
| 179 | + * |
| 180 | + * Lists are comma-separated indexes or ranges. |
| 181 | + * Ranges are dash separated indexes. |
| 182 | + * A bitmap containing bits 1, 33, 34, and all from 64 to 95 is printed as <tt>"1,33-34,64-95"</tt>. |
| 183 | + * The last range may not have an ending index if the bitmap is infinitely set. |
| 184 | + * |
| 185 | + * \return the number of characters that were written (not including the ending \c \0). |
| 186 | + * \return -1 on error, for instance with \p errno set to \c ENOMEM on failure to allocate the output string. |
157 | 187 | */ |
158 | 188 | HWLOC_DECLSPEC int hwloc_bitmap_list_asprintf(char ** strp, hwloc_const_bitmap_t bitmap); |
159 | 189 |
|
160 | 190 | /** \brief Parse a list string and stores it in bitmap \p bitmap. |
| 191 | + * |
| 192 | + * <b>Note that if the bitmap is a CPU or nodeset, the input string must contain physical indexes.</b> |
| 193 | + * |
| 194 | + * Lists are comma-separated indexes or ranges. |
| 195 | + * Ranges are dash separated indexes. |
| 196 | + * String <tt>"1,33-34,64-95"</tt> is parsed as a bitmap containing bits 1, 33, 34, and all from 64 to 95. |
| 197 | + * The last range may not have an ending index if the bitmap is infinitely set. |
161 | 198 | * |
162 | 199 | * \return 0 on success, -1 on error. |
163 | 200 | */ |
164 | 201 | HWLOC_DECLSPEC int hwloc_bitmap_list_sscanf(hwloc_bitmap_t bitmap, const char * __hwloc_restrict string); |
165 | 202 |
|
166 | 203 | /** \brief Stringify a bitmap in the taskset-specific format. |
167 | 204 | * |
168 | | - * The taskset command manipulates bitmap strings that contain a single |
| 205 | + * <b>Note that if the bitmap is a CPU or nodeset, it contains physical indexes.</b> |
| 206 | + * |
| 207 | + * The taskset program manipulates bitmap strings that contain a single |
169 | 208 | * (possible very long) hexadecimal number starting with 0x. |
| 209 | + * A bitmap containing bits 1, 33, 34, and all from 64 to 95 is printed as </tt>"0xffffffff0000000600000002"</tt>. |
170 | 210 | * |
171 | 211 | * Up to \p buflen characters may be written in buffer \p buf. |
172 | 212 | * |
173 | 213 | * If \p buflen is 0, \p buf may safely be \c NULL. |
174 | 214 | * |
175 | 215 | * \return the number of characters that were actually written if not truncating, |
176 | | - * or that would have been written (not including the ending \\0). |
| 216 | + * or that would have been written (not including the ending \c \0). |
| 217 | + * \return -1 on error. |
177 | 218 | */ |
178 | 219 | HWLOC_DECLSPEC int hwloc_bitmap_taskset_snprintf(char * __hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap); |
179 | 220 |
|
180 | 221 | /** \brief Stringify a bitmap into a newly allocated taskset-specific string. |
181 | 222 | * |
182 | | - * \return 0 on success, -1 on error. |
| 223 | + * <b>Note that if the bitmap is a CPU or nodeset, it contains physical indexes.</b> |
| 224 | + * |
| 225 | + * The taskset program manipulates bitmap strings that contain a single |
| 226 | + * (possible very long) hexadecimal number starting with 0x. |
| 227 | + * A bitmap containing bits 1, 33, 34, and all from 64 to 95 is printed as <tt>"0xffffffff0000000600000002"</tt>. |
| 228 | + * |
| 229 | + * \return the number of characters that were written (not including the ending \c \0). |
| 230 | + * \return -1 on error, for instance with \p errno set to \c ENOMEM on failure to allocate the output string. |
183 | 231 | */ |
184 | 232 | HWLOC_DECLSPEC int hwloc_bitmap_taskset_asprintf(char ** strp, hwloc_const_bitmap_t bitmap); |
185 | 233 |
|
186 | 234 | /** \brief Parse a taskset-specific bitmap string and stores it in bitmap \p bitmap. |
| 235 | + * |
| 236 | + * <b>Note that if the bitmap is a CPU or nodeset, the input string must contain physical indexes.</b> |
| 237 | + * |
| 238 | + * The taskset program manipulates bitmap strings that contain a single |
| 239 | + * (possible very long) hexadecimal number starting with 0x. |
| 240 | + * String <tt>"0xffffffff0000000600000002"</tt> is parsed as a bitmap containing all bits between 64 and 95, |
| 241 | + * and bits 33, 34 and 1. |
187 | 242 | * |
188 | 243 | * \return 0 on success, -1 on error. |
189 | 244 | */ |
|
0 commit comments