• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 #ifndef U_HIDE_DRAFT_API
116 
117     /**
118      * The lowest resource/data location.
119      * @draft ICU 65
120      */
121     UTRACE_UDATA_START=0x3000,
122 
123     /**
124      * Indicates that a value was read from a resource bundle. Provides three
125      * C-style strings to UTraceData: type, file name, and resource path. The
126      * possible types are:
127      *
128      * - "string" (a string value was accessed)
129      * - "binary" (a binary value was accessed)
130      * - "intvector" (a integer vector value was accessed)
131      * - "int" (a signed integer value was accessed)
132      * - "uint" (a unsigned integer value was accessed)
133      * - "get" (a path was loaded, but the value was not accessed)
134      * - "getalias" (a path was loaded, and an alias was resolved)
135      *
136      * @draft ICU 65
137      */
138     UTRACE_UDATA_RESOURCE=UTRACE_UDATA_START,
139 
140     /**
141      * Indicates that a resource bundle was opened.
142      *
143      * Provides one C-style string to UTraceData: file name.
144      * @draft ICU 65
145      */
146     UTRACE_UDATA_BUNDLE,
147 
148     /**
149      * Indicates that a data file was opened, but not *.res files.
150      *
151      * Provides one C-style string to UTraceData: file name.
152      *
153      * @draft ICU 65
154      */
155     UTRACE_UDATA_DATA_FILE,
156 
157     /**
158      * Indicates that a *.res file was opened.
159      *
160      * This differs from UTRACE_UDATA_BUNDLE because a res file is typically
161      * opened only once per application runtime, but the bundle corresponding
162      * to that res file may be opened many times.
163      *
164      * Provides one C-style string to UTraceData: file name.
165      *
166      * @draft ICU 65
167      */
168     UTRACE_UDATA_RES_FILE,
169 
170 #endif  // U_HIDE_DRAFT_API
171 
172 #ifndef U_HIDE_INTERNAL_API
173     /**
174      * One more than the highest normal resource/data trace location.
175      * @internal The numeric value may change over time, see ICU ticket #12420.
176      */
177     UTRACE_RES_DATA_LIMIT,
178 #endif  // U_HIDE_INTERNAL_API
179 
180 } UTraceFunctionNumber;
181 
182 /**
183  * Setter for the trace level.
184  * @param traceLevel A UTraceLevel value.
185  * @stable ICU 2.8
186  */
187 U_STABLE void U_EXPORT2
188 utrace_setLevel(int32_t traceLevel);
189 
190 /**
191  * Getter for the trace level.
192  * @return The UTraceLevel value being used by ICU.
193  * @stable ICU 2.8
194  */
195 U_STABLE int32_t U_EXPORT2
196 utrace_getLevel(void);
197 
198 /* Trace function pointers types  ----------------------------- */
199 
200 /**
201   *  Type signature for the trace function to be called when entering a function.
202   *  @param context value supplied at the time the trace functions are set.
203   *  @param fnNumber Enum value indicating the ICU function being entered.
204   *  @stable ICU 2.8
205   */
206 typedef void U_CALLCONV
207 UTraceEntry(const void *context, int32_t fnNumber);
208 
209 /**
210   *  Type signature for the trace function to be called when exiting from a function.
211   *  @param context value supplied at the time the trace functions are set.
212   *  @param fnNumber Enum value indicating the ICU function being exited.
213   *  @param fmt     A formatting string that describes the number and types
214   *                 of arguments included with the variable args.  The fmt
215   *                 string has the same form as the utrace_vformat format
216   *                 string.
217   *  @param args    A variable arguments list.  Contents are described by
218   *                 the fmt parameter.
219   *  @see   utrace_vformat
220   *  @stable ICU 2.8
221   */
222 typedef void U_CALLCONV
223 UTraceExit(const void *context, int32_t fnNumber,
224            const char *fmt, va_list args);
225 
226 /**
227   *  Type signature for the trace function to be called from within an ICU function
228   *  to display data or messages.
229   *  @param context  value supplied at the time the trace functions are set.
230   *  @param fnNumber Enum value indicating the ICU function being exited.
231   *  @param level    The current tracing level
232   *  @param fmt      A format string describing the tracing data that is supplied
233   *                  as variable args
234   *  @param args     The data being traced, passed as variable args.
235   *  @stable ICU 2.8
236   */
237 typedef void U_CALLCONV
238 UTraceData(const void *context, int32_t fnNumber, int32_t level,
239            const char *fmt, va_list args);
240 
241 /**
242   *  Set ICU Tracing functions.  Installs application-provided tracing
243   *  functions into ICU.  After doing this, subsequent ICU operations
244   *  will call back to the installed functions, providing a trace
245   *  of the use of ICU.  Passing a NULL pointer for a tracing function
246   *  is allowed, and inhibits tracing action at points where that function
247   *  would be called.
248   *  <p>
249   *  Tracing and Threads:  Tracing functions are global to a process, and
250   *  will be called in response to ICU operations performed by any
251   *  thread.  If tracing of an individual thread is desired, the
252   *  tracing functions must themselves filter by checking that the
253   *  current thread is the desired thread.
254   *
255   *  @param context an uninterpreted pointer.  Whatever is passed in
256   *                 here will in turn be passed to each of the tracing
257   *                 functions UTraceEntry, UTraceExit and UTraceData.
258   *                 ICU does not use or alter this pointer.
259   *  @param e       Callback function to be called on entry to a
260   *                 a traced ICU function.
261   *  @param x       Callback function to be called on exit from a
262   *                 traced ICU function.
263   *  @param d       Callback function to be called from within a
264   *                 traced ICU function, for the purpose of providing
265   *                 data to the trace.
266   *
267   *  @stable ICU 2.8
268   */
269 U_STABLE void U_EXPORT2
270 utrace_setFunctions(const void *context,
271                     UTraceEntry *e, UTraceExit *x, UTraceData *d);
272 
273 /**
274   * Get the currently installed ICU tracing functions.   Note that a null function
275   *   pointer will be returned if no trace function has been set.
276   *
277   * @param context  The currently installed tracing context.
278   * @param e        The currently installed UTraceEntry function.
279   * @param x        The currently installed UTraceExit function.
280   * @param d        The currently installed UTraceData function.
281   * @stable ICU 2.8
282   */
283 U_STABLE void U_EXPORT2
284 utrace_getFunctions(const void **context,
285                     UTraceEntry **e, UTraceExit **x, UTraceData **d);
286 
287 
288 
289 /*
290  *
291  * ICU trace format string syntax
292  *
293  * Format Strings are passed to UTraceData functions, and define the
294  * number and types of the trace data being passed on each call.
295  *
296  * The UTraceData function, which is supplied by the application,
297  * not by ICU, can either forward the trace data (passed via
298  * varargs) and the format string back to ICU for formatting into
299  * a displayable string, or it can interpret the format itself,
300  * and do as it wishes with the trace data.
301  *
302  *
303  * Goals for the format string
304  * - basic data output
305  * - easy to use for trace programmer
306  * - sufficient provision for data types for trace output readability
307  * - well-defined types and binary portable APIs
308  *
309  * Non-goals
310  * - printf compatibility
311  * - fancy formatting
312  * - argument reordering and other internationalization features
313  *
314  * ICU trace format strings contain plain text with argument inserts,
315  * much like standard printf format strings.
316  * Each insert begins with a '%', then optionally contains a 'v',
317  * then exactly one type character.
318  * Two '%' in a row represent a '%' instead of an insert.
319  * The trace format strings need not have \n at the end.
320  *
321  *
322  * Types
323  * -----
324  *
325  * Type characters:
326  * - c A char character in the default codepage.
327  * - s A NUL-terminated char * string in the default codepage.
328  * - S A UChar * string.  Requires two params, (ptr, length).  Length=-1 for nul term.
329  * - b A byte (8-bit integer).
330  * - h A 16-bit integer.  Also a 16 bit Unicode code unit.
331  * - d A 32-bit integer.  Also a 20 bit Unicode code point value.
332  * - l A 64-bit integer.
333  * - p A data pointer.
334  *
335  * Vectors
336  * -------
337  *
338  * If the 'v' is not specified, then one item of the specified type
339  * is passed in.
340  * If the 'v' (for "vector") is specified, then a vector of items of the
341  * specified type is passed in, via a pointer to the first item
342  * and an int32_t value for the length of the vector.
343  * Length==-1 means zero or NUL termination.  Works for vectors of all types.
344  *
345  * Note:  %vS is a vector of (UChar *) strings.  The strings must
346  *        be nul terminated as there is no way to provide a
347  *        separate length parameter for each string.  The length
348  *        parameter (required for all vectors) is the number of
349  *        strings, not the length of the strings.
350  *
351  * Examples
352  * --------
353  *
354  * These examples show the parameters that will be passed to an application's
355  *   UTraceData() function for various formats.
356  *
357  * - the precise formatting is up to the application!
358  * - the examples use type casts for arguments only to _show_ the types of
359  *   arguments without needing variable declarations in the examples;
360  *   the type casts will not be necessary in actual code
361  *
362  * UTraceDataFunc(context, fnNumber, level,
363  *              "There is a character %c in the string %s.",   // Format String
364  *              (char)c, (const char *)s);                     // varargs parameters
365  * ->   There is a character 0x42 'B' in the string "Bravo".
366  *
367  * UTraceDataFunc(context, fnNumber, level,
368  *              "Vector of bytes %vb vector of chars %vc",
369  *              (const uint8_t *)bytes, (int32_t)bytesLength,
370  *              (const char *)chars, (int32_t)charsLength);
371  * ->  Vector of bytes
372  *      42 63 64 3f [4]
373  *     vector of chars
374  *      "Bcd?"[4]
375  *
376  * UTraceDataFunc(context, fnNumber, level,
377  *              "An int32_t %d and a whole bunch of them %vd",
378  *              (int32_t)-5, (const int32_t *)ints, (int32_t)intsLength);
379  * ->   An int32_t 0xfffffffb and a whole bunch of them
380  *      fffffffb 00000005 0000010a [3]
381  *
382  */
383 
384 
385 
386 /**
387   *  Trace output Formatter.  An application's UTraceData tracing functions may call
388   *                 back to this function to format the trace output in a
389   *                 human readable form.  Note that a UTraceData function may choose
390   *                 to not format the data;  it could, for example, save it in
391   *                 in the raw form it was received (more compact), leaving
392   *                 formatting for a later trace analysis tool.
393   *  @param outBuf  pointer to a buffer to receive the formatted output.  Output
394   *                 will be nul terminated if there is space in the buffer -
395   *                 if the length of the requested output < the output buffer size.
396   *  @param capacity  Length of the output buffer.
397   *  @param indent  Number of spaces to indent the output.  Intended to allow
398   *                 data displayed from nested functions to be indented for readability.
399   *  @param fmt     Format specification for the data to output
400   *  @param args    Data to be formatted.
401   *  @return        Length of formatted output, including the terminating NUL.
402   *                 If buffer capacity is insufficient, the required capacity is returned.
403   *  @stable ICU 2.8
404   */
405 U_STABLE int32_t U_EXPORT2
406 utrace_vformat(char *outBuf, int32_t capacity,
407               int32_t indent, const char *fmt,  va_list args);
408 
409 /**
410   *  Trace output Formatter.  An application's UTraceData tracing functions may call
411   *                 this function to format any additional trace data, beyond that
412   *                 provided by default, in human readable form with the same
413   *                 formatting conventions used by utrace_vformat().
414   *  @param outBuf  pointer to a buffer to receive the formatted output.  Output
415   *                 will be nul terminated if there is space in the buffer -
416   *                 if the length of the requested output < the output buffer size.
417   *  @param capacity  Length of the output buffer.
418   *  @param indent  Number of spaces to indent the output.  Intended to allow
419   *                 data displayed from nested functions to be indented for readability.
420   *  @param fmt     Format specification for the data to output
421   *  @param ...     Data to be formatted.
422   *  @return        Length of formatted output, including the terminating NUL.
423   *                 If buffer capacity is insufficient, the required capacity is returned.
424   *  @stable ICU 2.8
425   */
426 U_STABLE int32_t U_EXPORT2
427 utrace_format(char *outBuf, int32_t capacity,
428               int32_t indent, const char *fmt,  ...);
429 
430 
431 
432 /* Trace function numbers --------------------------------------------------- */
433 
434 /**
435  * Get the name of a function from its trace function number.
436  *
437  * @param fnNumber The trace number for an ICU function.
438  * @return The name string for the function.
439  *
440  * @see UTraceFunctionNumber
441  * @stable ICU 2.8
442  */
443 U_STABLE const char * U_EXPORT2
444 utrace_functionName(int32_t fnNumber);
445 
446 U_CDECL_END
447 
448 #endif
449