include/unicode/utrace.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 *******************************************************************************
0005 *
0006 *   Copyright (C) 2003-2013, International Business Machines
0007 *   Corporation and others.  All Rights Reserved.
0008 *
0009 *******************************************************************************
0010 *   file name:  utrace.h
0011 *   encoding:   UTF-8
0012 *   tab size:   8 (not used)
0013 *   indentation:4
0014 *
0015 *   created on: 2003aug06
0016 *   created by: Markus W. Scherer
0017 *
0018 *   Definitions for ICU tracing/logging.
0019 *
0020 */
0021
0022 #ifndef __UTRACE_H__
0023 #define __UTRACE_H__
0024
0025 #include <stdarg.h>
0026 #include "unicode/utypes.h"
0027
0028 /**
0029  * \file
0030  * \brief C API:  Definitions for ICU tracing/logging.
0031  *
0032  * This provides API for debugging the internals of ICU without the use of
0033  * a traditional debugger.
0034  *
0035  * By default, tracing is disabled in ICU. If you need to debug ICU with
0036  * tracing, please compile ICU with the --enable-tracing configure option.
0037  */
0038
0039 U_CDECL_BEGIN
0040
0041 /**
0042  * Trace severity levels.  Higher levels increase the verbosity of the trace output.
0043  * @see utrace_setLevel
0044  * @stable ICU 2.8
0045  */
0046 typedef enum UTraceLevel {
0047     /** Disable all tracing  @stable ICU 2.8*/
0048     UTRACE_OFF=-1,
0049     /** Trace error conditions only  @stable ICU 2.8*/
0050     UTRACE_ERROR=0,
0051     /** Trace errors and warnings  @stable ICU 2.8*/
0052     UTRACE_WARNING=3,
0053     /** Trace opens and closes of ICU services  @stable ICU 2.8*/
0054     UTRACE_OPEN_CLOSE=5,
0055     /** Trace an intermediate number of ICU operations  @stable ICU 2.8*/
0056     UTRACE_INFO=7,
0057     /** Trace the maximum number of ICU operations  @stable ICU 2.8*/
0058     UTRACE_VERBOSE=9
0059 } UTraceLevel;
0060
0061 /**
0062  *  These are the ICU functions that will be traced when tracing is enabled.
0063  *  @stable ICU 2.8
0064  */
0065 typedef enum UTraceFunctionNumber {
0066     UTRACE_FUNCTION_START=0,
0067     UTRACE_U_INIT=UTRACE_FUNCTION_START,
0068     UTRACE_U_CLEANUP,
0069
0070 #ifndef U_HIDE_DEPRECATED_API
0071     /**
0072      * One more than the highest normal collation trace location.
0073      * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
0074      */
0075     UTRACE_FUNCTION_LIMIT,
0076 #endif  // U_HIDE_DEPRECATED_API
0077
0078     UTRACE_CONVERSION_START=0x1000,
0079     UTRACE_UCNV_OPEN=UTRACE_CONVERSION_START,
0080     UTRACE_UCNV_OPEN_PACKAGE,
0081     UTRACE_UCNV_OPEN_ALGORITHMIC,
0082     UTRACE_UCNV_CLONE,
0083     UTRACE_UCNV_CLOSE,
0084     UTRACE_UCNV_FLUSH_CACHE,
0085     UTRACE_UCNV_LOAD,
0086     UTRACE_UCNV_UNLOAD,
0087
0088 #ifndef U_HIDE_DEPRECATED_API
0089     /**
0090      * One more than the highest normal collation trace location.
0091      * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
0092      */
0093     UTRACE_CONVERSION_LIMIT,
0094 #endif  // U_HIDE_DEPRECATED_API
0095
0096     UTRACE_COLLATION_START=0x2000,
0097     UTRACE_UCOL_OPEN=UTRACE_COLLATION_START,
0098     UTRACE_UCOL_CLOSE,
0099     UTRACE_UCOL_STRCOLL,
0100     UTRACE_UCOL_GET_SORTKEY,
0101     UTRACE_UCOL_GETLOCALE,
0102     UTRACE_UCOL_NEXTSORTKEYPART,
0103     UTRACE_UCOL_STRCOLLITER,
0104     UTRACE_UCOL_OPEN_FROM_SHORT_STRING,
0105     UTRACE_UCOL_STRCOLLUTF8, /**< @stable ICU 50 */
0106
0107 #ifndef U_HIDE_DEPRECATED_API
0108     /**
0109      * One more than the highest normal collation trace location.
0110      * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
0111      */
0112     UTRACE_COLLATION_LIMIT,
0113 #endif  // U_HIDE_DEPRECATED_API
0114
0115     /**
0116      * The lowest resource/data location.
0117      * @stable ICU 65
0118      */
0119     UTRACE_UDATA_START=0x3000,
0120
0121     /**
0122      * Indicates that a value was read from a resource bundle. Provides three
0123      * C-style strings to UTraceData: type, file name, and resource path. The
0124      * possible types are:
0125      *
0126      * - "string" (a string value was accessed)
0127      * - "binary" (a binary value was accessed)
0128      * - "intvector" (a integer vector value was accessed)
0129      * - "int" (a signed integer value was accessed)
0130      * - "uint" (a unsigned integer value was accessed)
0131      * - "get" (a path was loaded, but the value was not accessed)
0132      * - "getalias" (a path was loaded, and an alias was resolved)
0133      *
0134      * @stable ICU 65
0135      */
0136     UTRACE_UDATA_RESOURCE=UTRACE_UDATA_START,
0137
0138     /**
0139      * Indicates that a resource bundle was opened.
0140      *
0141      * Provides one C-style string to UTraceData: file name.
0142      * @stable ICU 65
0143      */
0144     UTRACE_UDATA_BUNDLE,
0145
0146     /**
0147      * Indicates that a data file was opened, but not *.res files.
0148      *
0149      * Provides one C-style string to UTraceData: file name.
0150      *
0151      * @stable ICU 65
0152      */
0153     UTRACE_UDATA_DATA_FILE,
0154
0155     /**
0156      * Indicates that a *.res file was opened.
0157      *
0158      * This differs from UTRACE_UDATA_BUNDLE because a res file is typically
0159      * opened only once per application runtime, but the bundle corresponding
0160      * to that res file may be opened many times.
0161      *
0162      * Provides one C-style string to UTraceData: file name.
0163      *
0164      * @stable ICU 65
0165      */
0166     UTRACE_UDATA_RES_FILE,
0167
0168 #ifndef U_HIDE_INTERNAL_API
0169     /**
0170      * One more than the highest normal resource/data trace location.
0171      * @internal The numeric value may change over time, see ICU ticket #12420.
0172      */
0173     UTRACE_RES_DATA_LIMIT,
0174 #endif  // U_HIDE_INTERNAL_API
0175
0176     /**
0177      * The lowest break iterator location.
0178      * @stable ICU 67
0179      */
0180     UTRACE_UBRK_START=0x4000,
0181
0182     /**
0183      * Indicates that a character instance of break iterator was created.
0184      *
0185      * @stable ICU 67
0186      */
0187     UTRACE_UBRK_CREATE_CHARACTER = UTRACE_UBRK_START,
0188
0189     /**
0190      * Indicates that a word instance of break iterator was created.
0191      *
0192      * @stable ICU 67
0193      */
0194     UTRACE_UBRK_CREATE_WORD,
0195
0196     /**
0197      * Indicates that a line instance of break iterator was created.
0198      *
0199      * Provides one C-style string to UTraceData: the lb value ("",
0200      * "loose", "strict", or "normal").
0201      *
0202      * @stable ICU 67
0203      */
0204     UTRACE_UBRK_CREATE_LINE,
0205
0206     /**
0207      * Indicates that a sentence instance of break iterator was created.
0208      *
0209      * @stable ICU 67
0210      */
0211     UTRACE_UBRK_CREATE_SENTENCE,
0212
0213     /**
0214      * Indicates that a title instance of break iterator was created.
0215      *
0216      * @stable ICU 67
0217      */
0218     UTRACE_UBRK_CREATE_TITLE,
0219
0220     /**
0221      * Indicates that an internal dictionary break engine was created.
0222      *
0223      * Provides one C-style string to UTraceData: the script code of what
0224      * the break engine cover ("Hani", "Khmr", "Laoo", "Mymr", or "Thai").
0225      *
0226      * @stable ICU 67
0227      */
0228     UTRACE_UBRK_CREATE_BREAK_ENGINE,
0229
0230 #ifndef U_HIDE_INTERNAL_API
0231     /**
0232      * One more than the highest normal break iterator trace location.
0233      * @internal The numeric value may change over time, see ICU ticket #12420.
0234      */
0235     UTRACE_UBRK_LIMIT,
0236 #endif  // U_HIDE_INTERNAL_API
0237
0238 } UTraceFunctionNumber;
0239
0240 /**
0241  * Setter for the trace level.
0242  * @param traceLevel A UTraceLevel value.
0243  * @stable ICU 2.8
0244  */
0245 U_CAPI void U_EXPORT2
0246 utrace_setLevel(int32_t traceLevel);
0247
0248 /**
0249  * Getter for the trace level.
0250  * @return The UTraceLevel value being used by ICU.
0251  * @stable ICU 2.8
0252  */
0253 U_CAPI int32_t U_EXPORT2
0254 utrace_getLevel(void);
0255
0256 /* Trace function pointers types  ----------------------------- */
0257
0258 /**
0259   *  Type signature for the trace function to be called when entering a function.
0260   *  @param context value supplied at the time the trace functions are set.
0261   *  @param fnNumber Enum value indicating the ICU function being entered.
0262   *  @stable ICU 2.8
0263   */
0264 typedef void U_CALLCONV
0265 UTraceEntry(const void *context, int32_t fnNumber);
0266
0267 /**
0268   *  Type signature for the trace function to be called when exiting from a function.
0269   *  @param context value supplied at the time the trace functions are set.
0270   *  @param fnNumber Enum value indicating the ICU function being exited.
0271   *  @param fmt     A formatting string that describes the number and types
0272   *                 of arguments included with the variable args.  The fmt
0273   *                 string has the same form as the utrace_vformat format
0274   *                 string.
0275   *  @param args    A variable arguments list.  Contents are described by
0276   *                 the fmt parameter.
0277   *  @see   utrace_vformat
0278   *  @stable ICU 2.8
0279   */
0280 typedef void U_CALLCONV
0281 UTraceExit(const void *context, int32_t fnNumber,
0282            const char *fmt, va_list args);
0283
0284 /**
0285   *  Type signature for the trace function to be called from within an ICU function
0286   *  to display data or messages.
0287   *  @param context  value supplied at the time the trace functions are set.
0288   *  @param fnNumber Enum value indicating the ICU function being exited.
0289   *  @param level    The current tracing level
0290   *  @param fmt      A format string describing the tracing data that is supplied
0291   *                  as variable args
0292   *  @param args     The data being traced, passed as variable args.
0293   *  @stable ICU 2.8
0294   */
0295 typedef void U_CALLCONV
0296 UTraceData(const void *context, int32_t fnNumber, int32_t level,
0297            const char *fmt, va_list args);
0298
0299 /**
0300   *  Set ICU Tracing functions.  Installs application-provided tracing
0301   *  functions into ICU.  After doing this, subsequent ICU operations
0302   *  will call back to the installed functions, providing a trace
0303   *  of the use of ICU.  Passing a NULL pointer for a tracing function
0304   *  is allowed, and inhibits tracing action at points where that function
0305   *  would be called.
0306   *  <p>
0307   *  Tracing and Threads:  Tracing functions are global to a process, and
0308   *  will be called in response to ICU operations performed by any
0309   *  thread.  If tracing of an individual thread is desired, the
0310   *  tracing functions must themselves filter by checking that the
0311   *  current thread is the desired thread.
0312   *
0313   *  @param context an uninterpreted pointer.  Whatever is passed in
0314   *                 here will in turn be passed to each of the tracing
0315   *                 functions UTraceEntry, UTraceExit and UTraceData.
0316   *                 ICU does not use or alter this pointer.
0317   *  @param e       Callback function to be called on entry to a
0318   *                 a traced ICU function.
0319   *  @param x       Callback function to be called on exit from a
0320   *                 traced ICU function.
0321   *  @param d       Callback function to be called from within a
0322   *                 traced ICU function, for the purpose of providing
0323   *                 data to the trace.
0324   *
0325   *  @stable ICU 2.8
0326   */
0327 U_CAPI void U_EXPORT2
0328 utrace_setFunctions(const void *context,
0329                     UTraceEntry *e, UTraceExit *x, UTraceData *d);
0330
0331 /**
0332   * Get the currently installed ICU tracing functions.   Note that a null function
0333   *   pointer will be returned if no trace function has been set.
0334   *
0335   * @param context  The currently installed tracing context.
0336   * @param e        The currently installed UTraceEntry function.
0337   * @param x        The currently installed UTraceExit function.
0338   * @param d        The currently installed UTraceData function.
0339   * @stable ICU 2.8
0340   */
0341 U_CAPI void U_EXPORT2
0342 utrace_getFunctions(const void **context,
0343                     UTraceEntry **e, UTraceExit **x, UTraceData **d);
0344
0345
0346
0347 /*
0348  *
0349  * ICU trace format string syntax
0350  *
0351  * Format Strings are passed to UTraceData functions, and define the
0352  * number and types of the trace data being passed on each call.
0353  *
0354  * The UTraceData function, which is supplied by the application,
0355  * not by ICU, can either forward the trace data (passed via
0356  * varargs) and the format string back to ICU for formatting into
0357  * a displayable string, or it can interpret the format itself,
0358  * and do as it wishes with the trace data.
0359  *
0360  *
0361  * Goals for the format string
0362  * - basic data output
0363  * - easy to use for trace programmer
0364  * - sufficient provision for data types for trace output readability
0365  * - well-defined types and binary portable APIs
0366  *
0367  * Non-goals
0368  * - printf compatibility
0369  * - fancy formatting
0370  * - argument reordering and other internationalization features
0371  *
0372  * ICU trace format strings contain plain text with argument inserts,
0373  * much like standard printf format strings.
0374  * Each insert begins with a '%', then optionally contains a 'v',
0375  * then exactly one type character.
0376  * Two '%' in a row represent a '%' instead of an insert.
0377  * The trace format strings need not have \n at the end.
0378  *
0379  *
0380  * Types
0381  * -----
0382  *
0383  * Type characters:
0384  * - c A char character in the default codepage.
0385  * - s A NUL-terminated char * string in the default codepage.
0386  * - S A UChar * string.  Requires two params, (ptr, length).  Length=-1 for nul term.
0387  * - b A byte (8-bit integer).
0388  * - h A 16-bit integer.  Also a 16 bit Unicode code unit.
0389  * - d A 32-bit integer.  Also a 20 bit Unicode code point value.
0390  * - l A 64-bit integer.
0391  * - p A data pointer.
0392  *
0393  * Vectors
0394  * -------
0395  *
0396  * If the 'v' is not specified, then one item of the specified type
0397  * is passed in.
0398  * If the 'v' (for "vector") is specified, then a vector of items of the
0399  * specified type is passed in, via a pointer to the first item
0400  * and an int32_t value for the length of the vector.
0401  * Length==-1 means zero or NUL termination.  Works for vectors of all types.
0402  *
0403  * Note:  %vS is a vector of (UChar *) strings.  The strings must
0404  *        be nul terminated as there is no way to provide a
0405  *        separate length parameter for each string.  The length
0406  *        parameter (required for all vectors) is the number of
0407  *        strings, not the length of the strings.
0408  *
0409  * Examples
0410  * --------
0411  *
0412  * These examples show the parameters that will be passed to an application's
0413  *   UTraceData() function for various formats.
0414  *
0415  * - the precise formatting is up to the application!
0416  * - the examples use type casts for arguments only to _show_ the types of
0417  *   arguments without needing variable declarations in the examples;
0418  *   the type casts will not be necessary in actual code
0419  *
0420  * UTraceDataFunc(context, fnNumber, level,
0421  *              "There is a character %c in the string %s.",   // Format String
0422  *              (char)c, (const char *)s);                     // varargs parameters
0423  * ->   There is a character 0x42 'B' in the string "Bravo".
0424  *
0425  * UTraceDataFunc(context, fnNumber, level,
0426  *              "Vector of bytes %vb vector of chars %vc",
0427  *              (const uint8_t *)bytes, (int32_t)bytesLength,
0428  *              (const char *)chars, (int32_t)charsLength);
0429  * ->  Vector of bytes
0430  *      42 63 64 3f [4]
0431  *     vector of chars
0432  *      "Bcd?"[4]
0433  *
0434  * UTraceDataFunc(context, fnNumber, level,
0435  *              "An int32_t %d and a whole bunch of them %vd",
0436  *              (int32_t)-5, (const int32_t *)ints, (int32_t)intsLength);
0437  * ->   An int32_t 0xfffffffb and a whole bunch of them
0438  *      fffffffb 00000005 0000010a [3]
0439  *
0440  */
0441
0442
0443
0444 /**
0445   *  Trace output Formatter.  An application's UTraceData tracing functions may call
0446   *                 back to this function to format the trace output in a
0447   *                 human readable form.  Note that a UTraceData function may choose
0448   *                 to not format the data;  it could, for example, save it in
0449   *                 in the raw form it was received (more compact), leaving
0450   *                 formatting for a later trace analysis tool.
0451   *  @param outBuf  pointer to a buffer to receive the formatted output.  Output
0452   *                 will be nul terminated if there is space in the buffer -
0453   *                 if the length of the requested output < the output buffer size.
0454   *  @param capacity  Length of the output buffer.
0455   *  @param indent  Number of spaces to indent the output.  Intended to allow
0456   *                 data displayed from nested functions to be indented for readability.
0457   *  @param fmt     Format specification for the data to output
0458   *  @param args    Data to be formatted.
0459   *  @return        Length of formatted output, including the terminating NUL.
0460   *                 If buffer capacity is insufficient, the required capacity is returned.
0461   *  @stable ICU 2.8
0462   */
0463 U_CAPI int32_t U_EXPORT2
0464 utrace_vformat(char *outBuf, int32_t capacity,
0465               int32_t indent, const char *fmt,  va_list args);
0466
0467 /**
0468   *  Trace output Formatter.  An application's UTraceData tracing functions may call
0469   *                 this function to format any additional trace data, beyond that
0470   *                 provided by default, in human readable form with the same
0471   *                 formatting conventions used by utrace_vformat().
0472   *  @param outBuf  pointer to a buffer to receive the formatted output.  Output
0473   *                 will be nul terminated if there is space in the buffer -
0474   *                 if the length of the requested output < the output buffer size.
0475   *  @param capacity  Length of the output buffer.
0476   *  @param indent  Number of spaces to indent the output.  Intended to allow
0477   *                 data displayed from nested functions to be indented for readability.
0478   *  @param fmt     Format specification for the data to output
0479   *  @param ...     Data to be formatted.
0480   *  @return        Length of formatted output, including the terminating NUL.
0481   *                 If buffer capacity is insufficient, the required capacity is returned.
0482   *  @stable ICU 2.8
0483   */
0484 U_CAPI int32_t U_EXPORT2
0485 utrace_format(char *outBuf, int32_t capacity,
0486               int32_t indent, const char *fmt,  ...);
0487
0488
0489
0490 /* Trace function numbers --------------------------------------------------- */
0491
0492 /**
0493  * Get the name of a function from its trace function number.
0494  *
0495  * @param fnNumber The trace number for an ICU function.
0496  * @return The name string for the function.
0497  *
0498  * @see UTraceFunctionNumber
0499  * @stable ICU 2.8
0500  */
0501 U_CAPI const char * U_EXPORT2
0502 utrace_functionName(int32_t fnNumber);
0503
0504 U_CDECL_END
0505
0506 #endif