1 | // © 2016 and later: Unicode, Inc. and others. |
2 | // License & terms of use: http://www.unicode.org/copyright.html |
3 | /* |
4 | ******************************************************************************* |
5 | * |
6 | * Copyright (C) 2003-2013, International Business Machines |
7 | * Corporation and others. All Rights Reserved. |
8 | * |
9 | ******************************************************************************* |
10 | * file name: utrace.h |
11 | * encoding: UTF-8 |
12 | * tab size: 8 (not used) |
13 | * indentation:4 |
14 | * |
15 | * created on: 2003aug06 |
16 | * created by: Markus W. Scherer |
17 | * |
18 | * Definitions for ICU tracing/logging. |
19 | * |
20 | */ |
21 | |
22 | #ifndef __UTRACE_H__ |
23 | #define __UTRACE_H__ |
24 | |
25 | #include <stdarg.h> |
26 | #include "unicode/utypes.h" |
27 | |
28 | /** |
29 | * \file |
30 | * \brief C API: Definitions for ICU tracing/logging. |
31 | * |
32 | * This provides API for debugging the internals of ICU without the use of |
33 | * a traditional debugger. |
34 | * |
35 | * By default, tracing is disabled in ICU. If you need to debug ICU with |
36 | * tracing, please compile ICU with the --enable-tracing configure option. |
37 | */ |
38 | |
39 | U_CDECL_BEGIN |
40 | |
41 | /** |
42 | * Trace severity levels. Higher levels increase the verbosity of the trace output. |
43 | * @see utrace_setLevel |
44 | * @stable ICU 2.8 |
45 | */ |
46 | typedef enum UTraceLevel { |
47 | /** Disable all tracing @stable ICU 2.8*/ |
48 | UTRACE_OFF=-1, |
49 | /** Trace error conditions only @stable ICU 2.8*/ |
50 | UTRACE_ERROR=0, |
51 | /** Trace errors and warnings @stable ICU 2.8*/ |
52 | UTRACE_WARNING=3, |
53 | /** Trace opens and closes of ICU services @stable ICU 2.8*/ |
54 | UTRACE_OPEN_CLOSE=5, |
55 | /** Trace an intermediate number of ICU operations @stable ICU 2.8*/ |
56 | UTRACE_INFO=7, |
57 | /** Trace the maximum number of ICU operations @stable ICU 2.8*/ |
58 | UTRACE_VERBOSE=9 |
59 | } UTraceLevel; |
60 | |
61 | /** |
62 | * These are the ICU functions that will be traced when tracing is enabled. |
63 | * @stable ICU 2.8 |
64 | */ |
65 | typedef enum UTraceFunctionNumber { |
66 | UTRACE_FUNCTION_START=0, |
67 | UTRACE_U_INIT=UTRACE_FUNCTION_START, |
68 | UTRACE_U_CLEANUP, |
69 | |
70 | #ifndef U_HIDE_DEPRECATED_API |
71 | /** |
72 | * One more than the highest normal collation trace location. |
73 | * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. |
74 | */ |
75 | UTRACE_FUNCTION_LIMIT, |
76 | #endif // U_HIDE_DEPRECATED_API |
77 | |
78 | UTRACE_CONVERSION_START=0x1000, |
79 | UTRACE_UCNV_OPEN=UTRACE_CONVERSION_START, |
80 | UTRACE_UCNV_OPEN_PACKAGE, |
81 | UTRACE_UCNV_OPEN_ALGORITHMIC, |
82 | UTRACE_UCNV_CLONE, |
83 | UTRACE_UCNV_CLOSE, |
84 | UTRACE_UCNV_FLUSH_CACHE, |
85 | UTRACE_UCNV_LOAD, |
86 | UTRACE_UCNV_UNLOAD, |
87 | |
88 | #ifndef U_HIDE_DEPRECATED_API |
89 | /** |
90 | * One more than the highest normal collation trace location. |
91 | * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. |
92 | */ |
93 | UTRACE_CONVERSION_LIMIT, |
94 | #endif // U_HIDE_DEPRECATED_API |
95 | |
96 | UTRACE_COLLATION_START=0x2000, |
97 | UTRACE_UCOL_OPEN=UTRACE_COLLATION_START, |
98 | UTRACE_UCOL_CLOSE, |
99 | UTRACE_UCOL_STRCOLL, |
100 | UTRACE_UCOL_GET_SORTKEY, |
101 | UTRACE_UCOL_GETLOCALE, |
102 | UTRACE_UCOL_NEXTSORTKEYPART, |
103 | UTRACE_UCOL_STRCOLLITER, |
104 | UTRACE_UCOL_OPEN_FROM_SHORT_STRING, |
105 | UTRACE_UCOL_STRCOLLUTF8, /**< @stable ICU 50 */ |
106 | |
107 | #ifndef U_HIDE_DEPRECATED_API |
108 | /** |
109 | * One more than the highest normal collation trace location. |
110 | * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. |
111 | */ |
112 | UTRACE_COLLATION_LIMIT, |
113 | #endif // U_HIDE_DEPRECATED_API |
114 | |
115 | /** |
116 | * The lowest resource/data location. |
117 | * @stable ICU 65 |
118 | */ |
119 | UTRACE_UDATA_START=0x3000, |
120 | |
121 | /** |
122 | * Indicates that a value was read from a resource bundle. Provides three |
123 | * C-style strings to UTraceData: type, file name, and resource path. The |
124 | * possible types are: |
125 | * |
126 | * - "string" (a string value was accessed) |
127 | * - "binary" (a binary value was accessed) |
128 | * - "intvector" (a integer vector value was accessed) |
129 | * - "int" (a signed integer value was accessed) |
130 | * - "uint" (a unsigned integer value was accessed) |
131 | * - "get" (a path was loaded, but the value was not accessed) |
132 | * - "getalias" (a path was loaded, and an alias was resolved) |
133 | * |
134 | * @stable ICU 65 |
135 | */ |
136 | UTRACE_UDATA_RESOURCE=UTRACE_UDATA_START, |
137 | |
138 | /** |
139 | * Indicates that a resource bundle was opened. |
140 | * |
141 | * Provides one C-style string to UTraceData: file name. |
142 | * @stable ICU 65 |
143 | */ |
144 | UTRACE_UDATA_BUNDLE, |
145 | |
146 | /** |
147 | * Indicates that a data file was opened, but not *.res files. |
148 | * |
149 | * Provides one C-style string to UTraceData: file name. |
150 | * |
151 | * @stable ICU 65 |
152 | */ |
153 | UTRACE_UDATA_DATA_FILE, |
154 | |
155 | /** |
156 | * Indicates that a *.res file was opened. |
157 | * |
158 | * This differs from UTRACE_UDATA_BUNDLE because a res file is typically |
159 | * opened only once per application runtime, but the bundle corresponding |
160 | * to that res file may be opened many times. |
161 | * |
162 | * Provides one C-style string to UTraceData: file name. |
163 | * |
164 | * @stable ICU 65 |
165 | */ |
166 | UTRACE_UDATA_RES_FILE, |
167 | |
168 | #ifndef U_HIDE_INTERNAL_API |
169 | /** |
170 | * One more than the highest normal resource/data trace location. |
171 | * @internal The numeric value may change over time, see ICU ticket #12420. |
172 | */ |
173 | UTRACE_RES_DATA_LIMIT, |
174 | #endif // U_HIDE_INTERNAL_API |
175 | |
176 | /** |
177 | * The lowest break iterator location. |
178 | * @stable ICU 67 |
179 | */ |
180 | UTRACE_UBRK_START=0x4000, |
181 | |
182 | /** |
183 | * Indicates that a character instance of break iterator was created. |
184 | * |
185 | * @stable ICU 67 |
186 | */ |
187 | UTRACE_UBRK_CREATE_CHARACTER = UTRACE_UBRK_START, |
188 | |
189 | /** |
190 | * Indicates that a word instance of break iterator was created. |
191 | * |
192 | * @stable ICU 67 |
193 | */ |
194 | UTRACE_UBRK_CREATE_WORD, |
195 | |
196 | /** |
197 | * Indicates that a line instance of break iterator was created. |
198 | * |
199 | * Provides one C-style string to UTraceData: the lb value ("", |
200 | * "loose", "strict", or "normal"). |
201 | * |
202 | * @stable ICU 67 |
203 | */ |
204 | UTRACE_UBRK_CREATE_LINE, |
205 | |
206 | /** |
207 | * Indicates that a sentence instance of break iterator was created. |
208 | * |
209 | * @stable ICU 67 |
210 | */ |
211 | UTRACE_UBRK_CREATE_SENTENCE, |
212 | |
213 | /** |
214 | * Indicates that a title instance of break iterator was created. |
215 | * |
216 | * @stable ICU 67 |
217 | */ |
218 | UTRACE_UBRK_CREATE_TITLE, |
219 | |
220 | /** |
221 | * Indicates that an internal dictionary break engine was created. |
222 | * |
223 | * Provides one C-style string to UTraceData: the script code of what |
224 | * the break engine cover ("Hani", "Khmr", "Laoo", "Mymr", or "Thai"). |
225 | * |
226 | * @stable ICU 67 |
227 | */ |
228 | UTRACE_UBRK_CREATE_BREAK_ENGINE, |
229 | |
230 | #ifndef U_HIDE_INTERNAL_API |
231 | /** |
232 | * One more than the highest normal break iterator trace location. |
233 | * @internal The numeric value may change over time, see ICU ticket #12420. |
234 | */ |
235 | UTRACE_UBRK_LIMIT, |
236 | #endif // U_HIDE_INTERNAL_API |
237 | |
238 | } UTraceFunctionNumber; |
239 | |
240 | /** |
241 | * Setter for the trace level. |
242 | * @param traceLevel A UTraceLevel value. |
243 | * @stable ICU 2.8 |
244 | */ |
245 | U_CAPI void U_EXPORT2 |
246 | utrace_setLevel(int32_t traceLevel); |
247 | |
248 | /** |
249 | * Getter for the trace level. |
250 | * @return The UTraceLevel value being used by ICU. |
251 | * @stable ICU 2.8 |
252 | */ |
253 | U_CAPI int32_t U_EXPORT2 |
254 | utrace_getLevel(void); |
255 | |
256 | /* Trace function pointers types ----------------------------- */ |
257 | |
258 | /** |
259 | * Type signature for the trace function to be called when entering a function. |
260 | * @param context value supplied at the time the trace functions are set. |
261 | * @param fnNumber Enum value indicating the ICU function being entered. |
262 | * @stable ICU 2.8 |
263 | */ |
264 | typedef void U_CALLCONV |
265 | UTraceEntry(const void *context, int32_t fnNumber); |
266 | |
267 | /** |
268 | * Type signature for the trace function to be called when exiting from a function. |
269 | * @param context value supplied at the time the trace functions are set. |
270 | * @param fnNumber Enum value indicating the ICU function being exited. |
271 | * @param fmt A formatting string that describes the number and types |
272 | * of arguments included with the variable args. The fmt |
273 | * string has the same form as the utrace_vformat format |
274 | * string. |
275 | * @param args A variable arguments list. Contents are described by |
276 | * the fmt parameter. |
277 | * @see utrace_vformat |
278 | * @stable ICU 2.8 |
279 | */ |
280 | typedef void U_CALLCONV |
281 | UTraceExit(const void *context, int32_t fnNumber, |
282 | const char *fmt, va_list args); |
283 | |
284 | /** |
285 | * Type signature for the trace function to be called from within an ICU function |
286 | * to display data or messages. |
287 | * @param context value supplied at the time the trace functions are set. |
288 | * @param fnNumber Enum value indicating the ICU function being exited. |
289 | * @param level The current tracing level |
290 | * @param fmt A format string describing the tracing data that is supplied |
291 | * as variable args |
292 | * @param args The data being traced, passed as variable args. |
293 | * @stable ICU 2.8 |
294 | */ |
295 | typedef void U_CALLCONV |
296 | UTraceData(const void *context, int32_t fnNumber, int32_t level, |
297 | const char *fmt, va_list args); |
298 | |
299 | /** |
300 | * Set ICU Tracing functions. Installs application-provided tracing |
301 | * functions into ICU. After doing this, subsequent ICU operations |
302 | * will call back to the installed functions, providing a trace |
303 | * of the use of ICU. Passing a NULL pointer for a tracing function |
304 | * is allowed, and inhibits tracing action at points where that function |
305 | * would be called. |
306 | * <p> |
307 | * Tracing and Threads: Tracing functions are global to a process, and |
308 | * will be called in response to ICU operations performed by any |
309 | * thread. If tracing of an individual thread is desired, the |
310 | * tracing functions must themselves filter by checking that the |
311 | * current thread is the desired thread. |
312 | * |
313 | * @param context an uninterpreted pointer. Whatever is passed in |
314 | * here will in turn be passed to each of the tracing |
315 | * functions UTraceEntry, UTraceExit and UTraceData. |
316 | * ICU does not use or alter this pointer. |
317 | * @param e Callback function to be called on entry to a |
318 | * a traced ICU function. |
319 | * @param x Callback function to be called on exit from a |
320 | * traced ICU function. |
321 | * @param d Callback function to be called from within a |
322 | * traced ICU function, for the purpose of providing |
323 | * data to the trace. |
324 | * |
325 | * @stable ICU 2.8 |
326 | */ |
327 | U_CAPI void U_EXPORT2 |
328 | utrace_setFunctions(const void *context, |
329 | UTraceEntry *e, UTraceExit *x, UTraceData *d); |
330 | |
331 | /** |
332 | * Get the currently installed ICU tracing functions. Note that a null function |
333 | * pointer will be returned if no trace function has been set. |
334 | * |
335 | * @param context The currently installed tracing context. |
336 | * @param e The currently installed UTraceEntry function. |
337 | * @param x The currently installed UTraceExit function. |
338 | * @param d The currently installed UTraceData function. |
339 | * @stable ICU 2.8 |
340 | */ |
341 | U_CAPI void U_EXPORT2 |
342 | utrace_getFunctions(const void **context, |
343 | UTraceEntry **e, UTraceExit **x, UTraceData **d); |
344 | |
345 | |
346 | |
347 | /* |
348 | * |
349 | * ICU trace format string syntax |
350 | * |
351 | * Format Strings are passed to UTraceData functions, and define the |
352 | * number and types of the trace data being passed on each call. |
353 | * |
354 | * The UTraceData function, which is supplied by the application, |
355 | * not by ICU, can either forward the trace data (passed via |
356 | * varargs) and the format string back to ICU for formatting into |
357 | * a displayable string, or it can interpret the format itself, |
358 | * and do as it wishes with the trace data. |
359 | * |
360 | * |
361 | * Goals for the format string |
362 | * - basic data output |
363 | * - easy to use for trace programmer |
364 | * - sufficient provision for data types for trace output readability |
365 | * - well-defined types and binary portable APIs |
366 | * |
367 | * Non-goals |
368 | * - printf compatibility |
369 | * - fancy formatting |
370 | * - argument reordering and other internationalization features |
371 | * |
372 | * ICU trace format strings contain plain text with argument inserts, |
373 | * much like standard printf format strings. |
374 | * Each insert begins with a '%', then optionally contains a 'v', |
375 | * then exactly one type character. |
376 | * Two '%' in a row represent a '%' instead of an insert. |
377 | * The trace format strings need not have \n at the end. |
378 | * |
379 | * |
380 | * Types |
381 | * ----- |
382 | * |
383 | * Type characters: |
384 | * - c A char character in the default codepage. |
385 | * - s A NUL-terminated char * string in the default codepage. |
386 | * - S A UChar * string. Requires two params, (ptr, length). Length=-1 for nul term. |
387 | * - b A byte (8-bit integer). |
388 | * - h A 16-bit integer. Also a 16 bit Unicode code unit. |
389 | * - d A 32-bit integer. Also a 20 bit Unicode code point value. |
390 | * - l A 64-bit integer. |
391 | * - p A data pointer. |
392 | * |
393 | * Vectors |
394 | * ------- |
395 | * |
396 | * If the 'v' is not specified, then one item of the specified type |
397 | * is passed in. |
398 | * If the 'v' (for "vector") is specified, then a vector of items of the |
399 | * specified type is passed in, via a pointer to the first item |
400 | * and an int32_t value for the length of the vector. |
401 | * Length==-1 means zero or NUL termination. Works for vectors of all types. |
402 | * |
403 | * Note: %vS is a vector of (UChar *) strings. The strings must |
404 | * be nul terminated as there is no way to provide a |
405 | * separate length parameter for each string. The length |
406 | * parameter (required for all vectors) is the number of |
407 | * strings, not the length of the strings. |
408 | * |
409 | * Examples |
410 | * -------- |
411 | * |
412 | * These examples show the parameters that will be passed to an application's |
413 | * UTraceData() function for various formats. |
414 | * |
415 | * - the precise formatting is up to the application! |
416 | * - the examples use type casts for arguments only to _show_ the types of |
417 | * arguments without needing variable declarations in the examples; |
418 | * the type casts will not be necessary in actual code |
419 | * |
420 | * UTraceDataFunc(context, fnNumber, level, |
421 | * "There is a character %c in the string %s.", // Format String |
422 | * (char)c, (const char *)s); // varargs parameters |
423 | * -> There is a character 0x42 'B' in the string "Bravo". |
424 | * |
425 | * UTraceDataFunc(context, fnNumber, level, |
426 | * "Vector of bytes %vb vector of chars %vc", |
427 | * (const uint8_t *)bytes, (int32_t)bytesLength, |
428 | * (const char *)chars, (int32_t)charsLength); |
429 | * -> Vector of bytes |
430 | * 42 63 64 3f [4] |
431 | * vector of chars |
432 | * "Bcd?"[4] |
433 | * |
434 | * UTraceDataFunc(context, fnNumber, level, |
435 | * "An int32_t %d and a whole bunch of them %vd", |
436 | * (int32_t)-5, (const int32_t *)ints, (int32_t)intsLength); |
437 | * -> An int32_t 0xfffffffb and a whole bunch of them |
438 | * fffffffb 00000005 0000010a [3] |
439 | * |
440 | */ |
441 | |
442 | |
443 | |
444 | /** |
445 | * Trace output Formatter. An application's UTraceData tracing functions may call |
446 | * back to this function to format the trace output in a |
447 | * human readable form. Note that a UTraceData function may choose |
448 | * to not format the data; it could, for example, save it in |
449 | * in the raw form it was received (more compact), leaving |
450 | * formatting for a later trace analysis tool. |
451 | * @param outBuf pointer to a buffer to receive the formatted output. Output |
452 | * will be nul terminated if there is space in the buffer - |
453 | * if the length of the requested output < the output buffer size. |
454 | * @param capacity Length of the output buffer. |
455 | * @param indent Number of spaces to indent the output. Intended to allow |
456 | * data displayed from nested functions to be indented for readability. |
457 | * @param fmt Format specification for the data to output |
458 | * @param args Data to be formatted. |
459 | * @return Length of formatted output, including the terminating NUL. |
460 | * If buffer capacity is insufficient, the required capacity is returned. |
461 | * @stable ICU 2.8 |
462 | */ |
463 | U_CAPI int32_t U_EXPORT2 |
464 | utrace_vformat(char *outBuf, int32_t capacity, |
465 | int32_t indent, const char *fmt, va_list args); |
466 | |
467 | /** |
468 | * Trace output Formatter. An application's UTraceData tracing functions may call |
469 | * this function to format any additional trace data, beyond that |
470 | * provided by default, in human readable form with the same |
471 | * formatting conventions used by utrace_vformat(). |
472 | * @param outBuf pointer to a buffer to receive the formatted output. Output |
473 | * will be nul terminated if there is space in the buffer - |
474 | * if the length of the requested output < the output buffer size. |
475 | * @param capacity Length of the output buffer. |
476 | * @param indent Number of spaces to indent the output. Intended to allow |
477 | * data displayed from nested functions to be indented for readability. |
478 | * @param fmt Format specification for the data to output |
479 | * @param ... Data to be formatted. |
480 | * @return Length of formatted output, including the terminating NUL. |
481 | * If buffer capacity is insufficient, the required capacity is returned. |
482 | * @stable ICU 2.8 |
483 | */ |
484 | U_CAPI int32_t U_EXPORT2 |
485 | utrace_format(char *outBuf, int32_t capacity, |
486 | int32_t indent, const char *fmt, ...); |
487 | |
488 | |
489 | |
490 | /* Trace function numbers --------------------------------------------------- */ |
491 | |
492 | /** |
493 | * Get the name of a function from its trace function number. |
494 | * |
495 | * @param fnNumber The trace number for an ICU function. |
496 | * @return The name string for the function. |
497 | * |
498 | * @see UTraceFunctionNumber |
499 | * @stable ICU 2.8 |
500 | */ |
501 | U_CAPI const char * U_EXPORT2 |
502 | utrace_functionName(int32_t fnNumber); |
503 | |
504 | U_CDECL_END |
505 | |
506 | #endif |
507 | |