ICU 64.2  64.2
Typedefs | Enumerations | Functions
utrace.h File Reference

C API: Definitions for ICU tracing/logging. More...

#include <stdarg.h>
#include "unicode/utypes.h"

Go to the source code of this file.

Typedefs

typedef enum UTraceLevel UTraceLevel
 Trace severity levels. More...
 
typedef enum UTraceFunctionNumber UTraceFunctionNumber
 These are the ICU functions that will be traced when tracing is enabled. More...
 
typedef void UTraceEntry(const void *context, int32_t fnNumber)
 Type signature for the trace function to be called when entering a function. More...
 
typedef void UTraceExit(const void *context, int32_t fnNumber, const char *fmt, va_list args)
 Type signature for the trace function to be called when exiting from a function. More...
 
typedef void UTraceData(const void *context, int32_t fnNumber, int32_t level, const char *fmt, va_list args)
 Type signature for the trace function to be called from within an ICU function to display data or messages. More...
 

Enumerations

enum  UTraceLevel {
  UTRACE_OFF =-1, UTRACE_ERROR =0, UTRACE_WARNING =3, UTRACE_OPEN_CLOSE =5,
  UTRACE_INFO =7, UTRACE_VERBOSE =9
}
 Trace severity levels. More...
 
enum  UTraceFunctionNumber {
  UTRACE_FUNCTION_START =0, UTRACE_U_INIT =UTRACE_FUNCTION_START, UTRACE_U_CLEANUP, UTRACE_FUNCTION_LIMIT,
  UTRACE_CONVERSION_START =0x1000, UTRACE_UCNV_OPEN =UTRACE_CONVERSION_START, UTRACE_UCNV_OPEN_PACKAGE, UTRACE_UCNV_OPEN_ALGORITHMIC,
  UTRACE_UCNV_CLONE, UTRACE_UCNV_CLOSE, UTRACE_UCNV_FLUSH_CACHE, UTRACE_UCNV_LOAD,
  UTRACE_UCNV_UNLOAD, UTRACE_CONVERSION_LIMIT, UTRACE_COLLATION_START =0x2000, UTRACE_UCOL_OPEN =UTRACE_COLLATION_START,
  UTRACE_UCOL_CLOSE, UTRACE_UCOL_STRCOLL, UTRACE_UCOL_GET_SORTKEY, UTRACE_UCOL_GETLOCALE,
  UTRACE_UCOL_NEXTSORTKEYPART, UTRACE_UCOL_STRCOLLITER, UTRACE_UCOL_OPEN_FROM_SHORT_STRING, UTRACE_UCOL_STRCOLLUTF8,
  UTRACE_COLLATION_LIMIT
}
 These are the ICU functions that will be traced when tracing is enabled. More...
 

Functions

void utrace_setLevel (int32_t traceLevel)
 Setter for the trace level. More...
 
int32_t utrace_getLevel (void)
 Getter for the trace level. More...
 
void utrace_setFunctions (const void *context, UTraceEntry *e, UTraceExit *x, UTraceData *d)
 Set ICU Tracing functions. More...
 
void utrace_getFunctions (const void **context, UTraceEntry **e, UTraceExit **x, UTraceData **d)
 Get the currently installed ICU tracing functions. More...
 
int32_t utrace_vformat (char *outBuf, int32_t capacity, int32_t indent, const char *fmt, va_list args)
 Trace output Formatter. More...
 
int32_t utrace_format (char *outBuf, int32_t capacity, int32_t indent, const char *fmt,...)
 Trace output Formatter. More...
 
const char * utrace_functionName (int32_t fnNumber)
 Get the name of a function from its trace function number. More...
 

Detailed Description

C API: Definitions for ICU tracing/logging.

This provides API for debugging the internals of ICU without the use of a traditional debugger.

By default, tracing is disabled in ICU. If you need to debug ICU with tracing, please compile ICU with the –enable-tracing configure option.

Definition in file utrace.h.

Typedef Documentation

◆ UTraceData

typedef void UTraceData(const void *context, int32_t fnNumber, int32_t level, const char *fmt, va_list args)

Type signature for the trace function to be called from within an ICU function to display data or messages.

Parameters
contextvalue supplied at the time the trace functions are set.
fnNumberEnum value indicating the ICU function being exited.
levelThe current tracing level
fmtA format string describing the tracing data that is supplied as variable args
argsThe data being traced, passed as variable args.
Stable:
ICU 2.8

Definition at line 169 of file utrace.h.

◆ UTraceEntry

typedef void UTraceEntry(const void *context, int32_t fnNumber)

Type signature for the trace function to be called when entering a function.

Parameters
contextvalue supplied at the time the trace functions are set.
fnNumberEnum value indicating the ICU function being entered.
Stable:
ICU 2.8

Definition at line 138 of file utrace.h.

◆ UTraceExit

typedef void UTraceExit(const void *context, int32_t fnNumber, const char *fmt, va_list args)

Type signature for the trace function to be called when exiting from a function.

Parameters
contextvalue supplied at the time the trace functions are set.
fnNumberEnum value indicating the ICU function being exited.
fmtA formatting string that describes the number and types of arguments included with the variable args. The fmt string has the same form as the utrace_vformat format string.
argsA variable arguments list. Contents are described by the fmt parameter.
See also
utrace_vformat
Stable:
ICU 2.8

Definition at line 154 of file utrace.h.

◆ UTraceFunctionNumber

These are the ICU functions that will be traced when tracing is enabled.

Stable:
ICU 2.8

◆ UTraceLevel

typedef enum UTraceLevel UTraceLevel

Trace severity levels.

Higher levels increase the verbosity of the trace output.

See also
utrace_setLevel
Stable:
ICU 2.8

Enumeration Type Documentation

◆ UTraceFunctionNumber

These are the ICU functions that will be traced when tracing is enabled.

Stable:
ICU 2.8
Enumerator
UTRACE_FUNCTION_LIMIT 

One more than the highest normal collation trace location.

Deprecated:
ICU 58 The numeric value may change over time, see ICU ticket #12420.
UTRACE_CONVERSION_LIMIT 

One more than the highest normal collation trace location.

Deprecated:
ICU 58 The numeric value may change over time, see ICU ticket #12420.
UTRACE_UCOL_STRCOLLUTF8 
Stable:
ICU 50
UTRACE_COLLATION_LIMIT 

One more than the highest normal collation trace location.

Deprecated:
ICU 58 The numeric value may change over time, see ICU ticket #12420.

Definition at line 65 of file utrace.h.

◆ UTraceLevel

Trace severity levels.

Higher levels increase the verbosity of the trace output.

See also
utrace_setLevel
Stable:
ICU 2.8
Enumerator
UTRACE_OFF 

Disable all tracing.

Stable:
ICU 2.8
UTRACE_ERROR 

Trace error conditions only.

Stable:
ICU 2.8
UTRACE_WARNING 

Trace errors and warnings.

Stable:
ICU 2.8
UTRACE_OPEN_CLOSE 

Trace opens and closes of ICU services.

Stable:
ICU 2.8
UTRACE_INFO 

Trace an intermediate number of ICU operations.

Stable:
ICU 2.8
UTRACE_VERBOSE 

Trace the maximum number of ICU operations.

Stable:
ICU 2.8

Definition at line 46 of file utrace.h.

Function Documentation

◆ utrace_format()

int32_t utrace_format ( char *  outBuf,
int32_t  capacity,
int32_t  indent,
const char *  fmt,
  ... 
)

Trace output Formatter.

An application's UTraceData tracing functions may call this function to format any additional trace data, beyond that provided by default, in human readable form with the same formatting conventions used by utrace_vformat().

Parameters
outBufpointer to a buffer to receive the formatted output. Output will be nul terminated if there is space in the buffer - if the length of the requested output < the output buffer size.
capacityLength of the output buffer.
indentNumber of spaces to indent the output. Intended to allow data displayed from nested functions to be indented for readability.
fmtFormat specification for the data to output
...Data to be formatted.
Returns
Length of formatted output, including the terminating NUL. If buffer capacity is insufficient, the required capacity is returned.
Stable:
ICU 2.8

◆ utrace_functionName()

const char* utrace_functionName ( int32_t  fnNumber)

Get the name of a function from its trace function number.

Parameters
fnNumberThe trace number for an ICU function.
Returns
The name string for the function.
See also
UTraceFunctionNumber
Stable:
ICU 2.8

◆ utrace_getFunctions()

void utrace_getFunctions ( const void **  context,
UTraceEntry **  e,
UTraceExit **  x,
UTraceData **  d 
)

Get the currently installed ICU tracing functions.

Note that a null function pointer will be returned if no trace function has been set.

Parameters
contextThe currently installed tracing context.
eThe currently installed UTraceEntry function.
xThe currently installed UTraceExit function.
dThe currently installed UTraceData function.
Stable:
ICU 2.8

◆ utrace_getLevel()

int32_t utrace_getLevel ( void  )

Getter for the trace level.

Returns
The UTraceLevel value being used by ICU.
Stable:
ICU 2.8

◆ utrace_setFunctions()

void utrace_setFunctions ( const void *  context,
UTraceEntry e,
UTraceExit x,
UTraceData d 
)

Set ICU Tracing functions.

Installs application-provided tracing functions into ICU. After doing this, subsequent ICU operations will call back to the installed functions, providing a trace of the use of ICU. Passing a NULL pointer for a tracing function is allowed, and inhibits tracing action at points where that function would be called.

Tracing and Threads: Tracing functions are global to a process, and will be called in response to ICU operations performed by any thread. If tracing of an individual thread is desired, the tracing functions must themselves filter by checking that the current thread is the desired thread.

Parameters
contextan uninterpreted pointer. Whatever is passed in here will in turn be passed to each of the tracing functions UTraceEntry, UTraceExit and UTraceData. ICU does not use or alter this pointer.
eCallback function to be called on entry to a a traced ICU function.
xCallback function to be called on exit from a traced ICU function.
dCallback function to be called from within a traced ICU function, for the purpose of providing data to the trace.
Stable:
ICU 2.8

◆ utrace_setLevel()

void utrace_setLevel ( int32_t  traceLevel)

Setter for the trace level.

Parameters
traceLevelA UTraceLevel value.
Stable:
ICU 2.8

◆ utrace_vformat()

int32_t utrace_vformat ( char *  outBuf,
int32_t  capacity,
int32_t  indent,
const char *  fmt,
va_list  args 
)

Trace output Formatter.

An application's UTraceData tracing functions may call back to this function to format the trace output in a human readable form. Note that a UTraceData function may choose to not format the data; it could, for example, save it in in the raw form it was received (more compact), leaving formatting for a later trace analysis tool.

Parameters
outBufpointer to a buffer to receive the formatted output. Output will be nul terminated if there is space in the buffer - if the length of the requested output < the output buffer size.
capacityLength of the output buffer.
indentNumber of spaces to indent the output. Intended to allow data displayed from nested functions to be indented for readability.
fmtFormat specification for the data to output
argsData to be formatted.
Returns
Length of formatted output, including the terminating NUL. If buffer capacity is insufficient, the required capacity is returned.
Stable:
ICU 2.8