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.
typedef enum UTraceFunctionNumber	UTraceFunctionNumber
	These are the ICU functions that will be traced when tracing is enabled.
typedef void	UTraceEntry(const void *context, int32_t fnNumber)
	Type signature for the trace function to be called when entering a function.
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.
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.

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 , UTRACE_UDATA_START =0x3000 , UTRACE_UDATA_RESOURCE =UTRACE_UDATA_START , UTRACE_UDATA_BUNDLE ,   UTRACE_UDATA_DATA_FILE , UTRACE_UDATA_RES_FILE , UTRACE_RES_DATA_LIMIT , UTRACE_UBRK_START =0x4000 ,   UTRACE_UBRK_CREATE_CHARACTER = UTRACE_UBRK_START , UTRACE_UBRK_CREATE_WORD , UTRACE_UBRK_CREATE_LINE , UTRACE_UBRK_CREATE_SENTENCE ,   UTRACE_UBRK_CREATE_TITLE , UTRACE_UBRK_CREATE_BREAK_ENGINE , UTRACE_UBRK_LIMIT }
	These are the ICU functions that will be traced when tracing is enabled. More...

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

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

context	value supplied at the time the trace functions are set.
fnNumber	Enum value indicating the ICU function being exited.
level	The current tracing level
fmt	A format string describing the tracing data that is supplied as variable args
args	The data being traced, passed as variable args.

Stable:

ICU 2.8

Definition at line 296 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

context	value supplied at the time the trace functions are set.
fnNumber	Enum value indicating the ICU function being entered.

Stable:

ICU 2.8

Definition at line 265 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

context	value supplied at the time the trace functions are set.
fnNumber	Enum value indicating the ICU function being exited.
fmt	A 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.
args	A variable arguments list. Contents are described by the fmt parameter.

See also

utrace_vformat

Stable:

ICU 2.8

Definition at line 281 of file utrace.h.

UTraceFunctionNumber

typedef enum UTraceFunctionNumber 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

enum 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.
UTRACE_UDATA_START	The lowest resource/data location. Stable: ICU 65
UTRACE_UDATA_RESOURCE	Indicates that a value was read from a resource bundle. Provides three C-style strings to UTraceData: type, file name, and resource path. The possible types are: "string" (a string value was accessed) "binary" (a binary value was accessed) "intvector" (a integer vector value was accessed) "int" (a signed integer value was accessed) "uint" (a unsigned integer value was accessed) "get" (a path was loaded, but the value was not accessed) "getalias" (a path was loaded, and an alias was resolved) Stable: ICU 65
UTRACE_UDATA_BUNDLE	Indicates that a resource bundle was opened. Provides one C-style string to UTraceData: file name. Stable: ICU 65
UTRACE_UDATA_DATA_FILE	Indicates that a data file was opened, but not *.res files. Provides one C-style string to UTraceData: file name. Stable: ICU 65
UTRACE_UDATA_RES_FILE	Indicates that a *.res file was opened. This differs from UTRACE_UDATA_BUNDLE because a res file is typically opened only once per application runtime, but the bundle corresponding to that res file may be opened many times. Provides one C-style string to UTraceData: file name. Stable: ICU 65
UTRACE_RES_DATA_LIMIT	One more than the highest normal resource/data trace location. Internal: Do not use. This API is for internal use only. The numeric value may change over time, see ICU ticket #12420.
UTRACE_UBRK_START	The lowest break iterator location. Stable: ICU 67
UTRACE_UBRK_CREATE_CHARACTER	Indicates that a character instance of break iterator was created. Stable: ICU 67
UTRACE_UBRK_CREATE_WORD	Indicates that a word instance of break iterator was created. Stable: ICU 67
UTRACE_UBRK_CREATE_LINE	Indicates that a line instance of break iterator was created. Provides one C-style string to UTraceData: the lb value ("", "loose", "strict", or "normal"). Stable: ICU 67
UTRACE_UBRK_CREATE_SENTENCE	Indicates that a sentence instance of break iterator was created. Stable: ICU 67
UTRACE_UBRK_CREATE_TITLE	Indicates that a title instance of break iterator was created. Stable: ICU 67
UTRACE_UBRK_CREATE_BREAK_ENGINE	Indicates that an internal dictionary break engine was created. Provides one C-style string to UTraceData: the script code of what the break engine cover ("Hani", "Khmr", "Laoo", "Mymr", or "Thai"). Stable: ICU 67
UTRACE_UBRK_LIMIT	One more than the highest normal break iterator trace location. Internal: Do not use. This API is for internal use only. The numeric value may change over time, see ICU ticket #12420.

Definition at line 65 of file utrace.h.

UTraceLevel

enum 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()

U_CAPI 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

outBuf	pointer 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.
capacity	Length of the output buffer.
indent	Number of spaces to indent the output. Intended to allow data displayed from nested functions to be indented for readability.
fmt	Format 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()

U_CAPI const char * utrace_functionName

(

int32_t

fnNumber

)

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

Parameters

fnNumber

The trace number for an ICU function.

Returns

The name string for the function.

See also

UTraceFunctionNumber

Stable:

ICU 2.8

utrace_getFunctions()

U_CAPI 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

context	The currently installed tracing context.
e	The currently installed UTraceEntry function.
x	The currently installed UTraceExit function.
d	The currently installed UTraceData function.

Stable:

ICU 2.8

utrace_getLevel()

U_CAPI int32_t utrace_getLevel

(

void

)

Getter for the trace level.

Returns

The UTraceLevel value being used by ICU.

Stable:

ICU 2.8

utrace_setFunctions()

U_CAPI 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

context	an 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.
e	Callback function to be called on entry to a a traced ICU function.
x	Callback function to be called on exit from a traced ICU function.
d	Callback 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()

U_CAPI void utrace_setLevel

(

int32_t

traceLevel

)

Setter for the trace level.

Parameters

traceLevel

A UTraceLevel value.

Stable:

ICU 2.8

utrace_vformat()

U_CAPI 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

outBuf	pointer 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.
capacity	Length of the output buffer.
indent	Number of spaces to indent the output. Intended to allow data displayed from nested functions to be indented for readability.
fmt	Format specification for the data to output
args	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