1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/unicode/utrace.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,359 @@
1.4 +/*
1.5 +*******************************************************************************
1.6 +*
1.7 +* Copyright (C) 2003-2013, International Business Machines
1.8 +* Corporation and others. All Rights Reserved.
1.9 +*
1.10 +*******************************************************************************
1.11 +* file name: utrace.h
1.12 +* encoding: US-ASCII
1.13 +* tab size: 8 (not used)
1.14 +* indentation:4
1.15 +*
1.16 +* created on: 2003aug06
1.17 +* created by: Markus W. Scherer
1.18 +*
1.19 +* Definitions for ICU tracing/logging.
1.20 +*
1.21 +*/
1.22 +
1.23 +#ifndef __UTRACE_H__
1.24 +#define __UTRACE_H__
1.25 +
1.26 +#include <stdarg.h>
1.27 +#include "unicode/utypes.h"
1.28 +
1.29 +/**
1.30 + * \file
1.31 + * \brief C API: Definitions for ICU tracing/logging.
1.32 + *
1.33 + * This provides API for debugging the internals of ICU without the use of
1.34 + * a traditional debugger.
1.35 + *
1.36 + * By default, tracing is disabled in ICU. If you need to debug ICU with
1.37 + * tracing, please compile ICU with the --enable-tracing configure option.
1.38 + */
1.39 +
1.40 +U_CDECL_BEGIN
1.41 +
1.42 +/**
1.43 + * Trace severity levels. Higher levels increase the verbosity of the trace output.
1.44 + * @see utrace_setLevel
1.45 + * @stable ICU 2.8
1.46 + */
1.47 +typedef enum UTraceLevel {
1.48 + /** Disable all tracing @stable ICU 2.8*/
1.49 + UTRACE_OFF=-1,
1.50 + /** Trace error conditions only @stable ICU 2.8*/
1.51 + UTRACE_ERROR=0,
1.52 + /** Trace errors and warnings @stable ICU 2.8*/
1.53 + UTRACE_WARNING=3,
1.54 + /** Trace opens and closes of ICU services @stable ICU 2.8*/
1.55 + UTRACE_OPEN_CLOSE=5,
1.56 + /** Trace an intermediate number of ICU operations @stable ICU 2.8*/
1.57 + UTRACE_INFO=7,
1.58 + /** Trace the maximum number of ICU operations @stable ICU 2.8*/
1.59 + UTRACE_VERBOSE=9
1.60 +} UTraceLevel;
1.61 +
1.62 +/**
1.63 + * These are the ICU functions that will be traced when tracing is enabled.
1.64 + * @stable ICU 2.8
1.65 + */
1.66 +typedef enum UTraceFunctionNumber {
1.67 + UTRACE_FUNCTION_START=0,
1.68 + UTRACE_U_INIT=UTRACE_FUNCTION_START,
1.69 + UTRACE_U_CLEANUP,
1.70 + UTRACE_FUNCTION_LIMIT,
1.71 +
1.72 + UTRACE_CONVERSION_START=0x1000,
1.73 + UTRACE_UCNV_OPEN=UTRACE_CONVERSION_START,
1.74 + UTRACE_UCNV_OPEN_PACKAGE,
1.75 + UTRACE_UCNV_OPEN_ALGORITHMIC,
1.76 + UTRACE_UCNV_CLONE,
1.77 + UTRACE_UCNV_CLOSE,
1.78 + UTRACE_UCNV_FLUSH_CACHE,
1.79 + UTRACE_UCNV_LOAD,
1.80 + UTRACE_UCNV_UNLOAD,
1.81 + UTRACE_CONVERSION_LIMIT,
1.82 +
1.83 + UTRACE_COLLATION_START=0x2000,
1.84 + UTRACE_UCOL_OPEN=UTRACE_COLLATION_START,
1.85 + UTRACE_UCOL_CLOSE,
1.86 + UTRACE_UCOL_STRCOLL,
1.87 + UTRACE_UCOL_GET_SORTKEY,
1.88 + UTRACE_UCOL_GETLOCALE,
1.89 + UTRACE_UCOL_NEXTSORTKEYPART,
1.90 + UTRACE_UCOL_STRCOLLITER,
1.91 + UTRACE_UCOL_OPEN_FROM_SHORT_STRING,
1.92 + UTRACE_UCOL_STRCOLLUTF8, /**< @stable ICU 50 */
1.93 + UTRACE_COLLATION_LIMIT
1.94 +} UTraceFunctionNumber;
1.95 +
1.96 +/**
1.97 + * Setter for the trace level.
1.98 + * @param traceLevel A UTraceLevel value.
1.99 + * @stable ICU 2.8
1.100 + */
1.101 +U_STABLE void U_EXPORT2
1.102 +utrace_setLevel(int32_t traceLevel);
1.103 +
1.104 +/**
1.105 + * Getter for the trace level.
1.106 + * @return The UTraceLevel value being used by ICU.
1.107 + * @stable ICU 2.8
1.108 + */
1.109 +U_STABLE int32_t U_EXPORT2
1.110 +utrace_getLevel(void);
1.111 +
1.112 +/* Trace function pointers types ----------------------------- */
1.113 +
1.114 +/**
1.115 + * Type signature for the trace function to be called when entering a function.
1.116 + * @param context value supplied at the time the trace functions are set.
1.117 + * @param fnNumber Enum value indicating the ICU function being entered.
1.118 + * @stable ICU 2.8
1.119 + */
1.120 +typedef void U_CALLCONV
1.121 +UTraceEntry(const void *context, int32_t fnNumber);
1.122 +
1.123 +/**
1.124 + * Type signature for the trace function to be called when exiting from a function.
1.125 + * @param context value supplied at the time the trace functions are set.
1.126 + * @param fnNumber Enum value indicating the ICU function being exited.
1.127 + * @param fmt A formatting string that describes the number and types
1.128 + * of arguments included with the variable args. The fmt
1.129 + * string has the same form as the utrace_vformat format
1.130 + * string.
1.131 + * @param args A variable arguments list. Contents are described by
1.132 + * the fmt parameter.
1.133 + * @see utrace_vformat
1.134 + * @stable ICU 2.8
1.135 + */
1.136 +typedef void U_CALLCONV
1.137 +UTraceExit(const void *context, int32_t fnNumber,
1.138 + const char *fmt, va_list args);
1.139 +
1.140 +/**
1.141 + * Type signature for the trace function to be called from within an ICU function
1.142 + * to display data or messages.
1.143 + * @param context value supplied at the time the trace functions are set.
1.144 + * @param fnNumber Enum value indicating the ICU function being exited.
1.145 + * @param level The current tracing level
1.146 + * @param fmt A format string describing the tracing data that is supplied
1.147 + * as variable args
1.148 + * @param args The data being traced, passed as variable args.
1.149 + * @stable ICU 2.8
1.150 + */
1.151 +typedef void U_CALLCONV
1.152 +UTraceData(const void *context, int32_t fnNumber, int32_t level,
1.153 + const char *fmt, va_list args);
1.154 +
1.155 +/**
1.156 + * Set ICU Tracing functions. Installs application-provided tracing
1.157 + * functions into ICU. After doing this, subsequent ICU operations
1.158 + * will call back to the installed functions, providing a trace
1.159 + * of the use of ICU. Passing a NULL pointer for a tracing function
1.160 + * is allowed, and inhibits tracing action at points where that function
1.161 + * would be called.
1.162 + * <p>
1.163 + * Tracing and Threads: Tracing functions are global to a process, and
1.164 + * will be called in response to ICU operations performed by any
1.165 + * thread. If tracing of an individual thread is desired, the
1.166 + * tracing functions must themselves filter by checking that the
1.167 + * current thread is the desired thread.
1.168 + *
1.169 + * @param context an uninterpretted pointer. Whatever is passed in
1.170 + * here will in turn be passed to each of the tracing
1.171 + * functions UTraceEntry, UTraceExit and UTraceData.
1.172 + * ICU does not use or alter this pointer.
1.173 + * @param e Callback function to be called on entry to a
1.174 + * a traced ICU function.
1.175 + * @param x Callback function to be called on exit from a
1.176 + * traced ICU function.
1.177 + * @param d Callback function to be called from within a
1.178 + * traced ICU function, for the purpose of providing
1.179 + * data to the trace.
1.180 + *
1.181 + * @stable ICU 2.8
1.182 + */
1.183 +U_STABLE void U_EXPORT2
1.184 +utrace_setFunctions(const void *context,
1.185 + UTraceEntry *e, UTraceExit *x, UTraceData *d);
1.186 +
1.187 +/**
1.188 + * Get the currently installed ICU tracing functions. Note that a null function
1.189 + * pointer will be returned if no trace function has been set.
1.190 + *
1.191 + * @param context The currently installed tracing context.
1.192 + * @param e The currently installed UTraceEntry function.
1.193 + * @param x The currently installed UTraceExit function.
1.194 + * @param d The currently installed UTraceData function.
1.195 + * @stable ICU 2.8
1.196 + */
1.197 +U_STABLE void U_EXPORT2
1.198 +utrace_getFunctions(const void **context,
1.199 + UTraceEntry **e, UTraceExit **x, UTraceData **d);
1.200 +
1.201 +
1.202 +
1.203 +/*
1.204 + *
1.205 + * ICU trace format string syntax
1.206 + *
1.207 + * Format Strings are passed to UTraceData functions, and define the
1.208 + * number and types of the trace data being passed on each call.
1.209 + *
1.210 + * The UTraceData function, which is supplied by the application,
1.211 + * not by ICU, can either forward the trace data (passed via
1.212 + * varargs) and the format string back to ICU for formatting into
1.213 + * a displayable string, or it can interpret the format itself,
1.214 + * and do as it wishes with the trace data.
1.215 + *
1.216 + *
1.217 + * Goals for the format string
1.218 + * - basic data output
1.219 + * - easy to use for trace programmer
1.220 + * - sufficient provision for data types for trace output readability
1.221 + * - well-defined types and binary portable APIs
1.222 + *
1.223 + * Non-goals
1.224 + * - printf compatibility
1.225 + * - fancy formatting
1.226 + * - argument reordering and other internationalization features
1.227 + *
1.228 + * ICU trace format strings contain plain text with argument inserts,
1.229 + * much like standard printf format strings.
1.230 + * Each insert begins with a '%', then optionally contains a 'v',
1.231 + * then exactly one type character.
1.232 + * Two '%' in a row represent a '%' instead of an insert.
1.233 + * The trace format strings need not have \n at the end.
1.234 + *
1.235 + *
1.236 + * Types
1.237 + * -----
1.238 + *
1.239 + * Type characters:
1.240 + * - c A char character in the default codepage.
1.241 + * - s A NUL-terminated char * string in the default codepage.
1.242 + * - S A UChar * string. Requires two params, (ptr, length). Length=-1 for nul term.
1.243 + * - b A byte (8-bit integer).
1.244 + * - h A 16-bit integer. Also a 16 bit Unicode code unit.
1.245 + * - d A 32-bit integer. Also a 20 bit Unicode code point value.
1.246 + * - l A 64-bit integer.
1.247 + * - p A data pointer.
1.248 + *
1.249 + * Vectors
1.250 + * -------
1.251 + *
1.252 + * If the 'v' is not specified, then one item of the specified type
1.253 + * is passed in.
1.254 + * If the 'v' (for "vector") is specified, then a vector of items of the
1.255 + * specified type is passed in, via a pointer to the first item
1.256 + * and an int32_t value for the length of the vector.
1.257 + * Length==-1 means zero or NUL termination. Works for vectors of all types.
1.258 + *
1.259 + * Note: %vS is a vector of (UChar *) strings. The strings must
1.260 + * be nul terminated as there is no way to provide a
1.261 + * separate length parameter for each string. The length
1.262 + * parameter (required for all vectors) is the number of
1.263 + * strings, not the length of the strings.
1.264 + *
1.265 + * Examples
1.266 + * --------
1.267 + *
1.268 + * These examples show the parameters that will be passed to an application's
1.269 + * UTraceData() function for various formats.
1.270 + *
1.271 + * - the precise formatting is up to the application!
1.272 + * - the examples use type casts for arguments only to _show_ the types of
1.273 + * arguments without needing variable declarations in the examples;
1.274 + * the type casts will not be necessary in actual code
1.275 + *
1.276 + * UTraceDataFunc(context, fnNumber, level,
1.277 + * "There is a character %c in the string %s.", // Format String
1.278 + * (char)c, (const char *)s); // varargs parameters
1.279 + * -> There is a character 0x42 'B' in the string "Bravo".
1.280 + *
1.281 + * UTraceDataFunc(context, fnNumber, level,
1.282 + * "Vector of bytes %vb vector of chars %vc",
1.283 + * (const uint8_t *)bytes, (int32_t)bytesLength,
1.284 + * (const char *)chars, (int32_t)charsLength);
1.285 + * -> Vector of bytes
1.286 + * 42 63 64 3f [4]
1.287 + * vector of chars
1.288 + * "Bcd?"[4]
1.289 + *
1.290 + * UTraceDataFunc(context, fnNumber, level,
1.291 + * "An int32_t %d and a whole bunch of them %vd",
1.292 + * (int32_t)-5, (const int32_t *)ints, (int32_t)intsLength);
1.293 + * -> An int32_t 0xfffffffb and a whole bunch of them
1.294 + * fffffffb 00000005 0000010a [3]
1.295 + *
1.296 + */
1.297 +
1.298 +
1.299 +
1.300 +/**
1.301 + * Trace output Formatter. An application's UTraceData tracing functions may call
1.302 + * back to this function to format the trace output in a
1.303 + * human readable form. Note that a UTraceData function may choose
1.304 + * to not format the data; it could, for example, save it in
1.305 + * in the raw form it was received (more compact), leaving
1.306 + * formatting for a later trace analyis tool.
1.307 + * @param outBuf pointer to a buffer to receive the formatted output. Output
1.308 + * will be nul terminated if there is space in the buffer -
1.309 + * if the length of the requested output < the output buffer size.
1.310 + * @param capacity Length of the output buffer.
1.311 + * @param indent Number of spaces to indent the output. Intended to allow
1.312 + * data displayed from nested functions to be indented for readability.
1.313 + * @param fmt Format specification for the data to output
1.314 + * @param args Data to be formatted.
1.315 + * @return Length of formatted output, including the terminating NUL.
1.316 + * If buffer capacity is insufficient, the required capacity is returned.
1.317 + * @stable ICU 2.8
1.318 + */
1.319 +U_STABLE int32_t U_EXPORT2
1.320 +utrace_vformat(char *outBuf, int32_t capacity,
1.321 + int32_t indent, const char *fmt, va_list args);
1.322 +
1.323 +/**
1.324 + * Trace output Formatter. An application's UTraceData tracing functions may call
1.325 + * this function to format any additional trace data, beyond that
1.326 + * provided by default, in human readable form with the same
1.327 + * formatting conventions used by utrace_vformat().
1.328 + * @param outBuf pointer to a buffer to receive the formatted output. Output
1.329 + * will be nul terminated if there is space in the buffer -
1.330 + * if the length of the requested output < the output buffer size.
1.331 + * @param capacity Length of the output buffer.
1.332 + * @param indent Number of spaces to indent the output. Intended to allow
1.333 + * data displayed from nested functions to be indented for readability.
1.334 + * @param fmt Format specification for the data to output
1.335 + * @param ... Data to be formatted.
1.336 + * @return Length of formatted output, including the terminating NUL.
1.337 + * If buffer capacity is insufficient, the required capacity is returned.
1.338 + * @stable ICU 2.8
1.339 + */
1.340 +U_STABLE int32_t U_EXPORT2
1.341 +utrace_format(char *outBuf, int32_t capacity,
1.342 + int32_t indent, const char *fmt, ...);
1.343 +
1.344 +
1.345 +
1.346 +/* Trace function numbers --------------------------------------------------- */
1.347 +
1.348 +/**
1.349 + * Get the name of a function from its trace function number.
1.350 + *
1.351 + * @param fnNumber The trace number for an ICU function.
1.352 + * @return The name string for the function.
1.353 + *
1.354 + * @see UTraceFunctionNumber
1.355 + * @stable ICU 2.8
1.356 + */
1.357 +U_STABLE const char * U_EXPORT2
1.358 +utrace_functionName(int32_t fnNumber);
1.359 +
1.360 +U_CDECL_END
1.361 +
1.362 +#endif
