Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/utrace.h @ 69:33d812a61356

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