00001 # Debugging trace and error logging {#api_trace}
00002
00003 librsync can output trace or log messages as it proceeds.
00004 Error
00005 messages supplement return codes by describing in more detail what went
00006 wrong. Debug messages are useful when debugging librsync or applications
00007 that call it.
00008
00009 These
00010 follow a fairly standard priority-based filtering system
00011 (rs_trace_set_level()), using the same severity levels as UNIX syslog.
00012 Messages by default are sent to stderr, but may be passed to an
00013 application-provided callback (rs_trace_to(), rs_trace_fn_t()).
00014
00015 The default configuration is that warning and error messages are written
00016 to stderr. This should be appropriate for many applications. If it is
00017 not, the level and destination of messages may be changed.
00018
00019 Messages are passed out of librsync through a trace callback which is
00020 passed a severity and message string. The type for this callback is
00021 \ref rs_trace_fn_t.
00022
00023 The default trace function is \ref rs_trace_stderr.
00024
00025 The trace callback may be changed at runtime with \ref rs_trace_to.
00026
00027 Messages from librsync are labelled with a severity indicator of
00028 enumerated type \ref rs_loglevel.
00029
00030 The application may also specify a minimum severity of interest through
00031 \ref rs_trace_set_level.
00032 Messages lower than the specified level
00033 are discarded without being passed to the trace callback.