diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/trace.md | 33 |
1 files changed, 33 insertions, 0 deletions
diff --git a/doc/trace.md b/doc/trace.md new file mode 100644 index 0000000..b622739 --- /dev/null +++ b/doc/trace.md @@ -0,0 +1,33 @@ +# Debugging trace and error logging {#api_trace} + +librsync can output trace or log messages as it proceeds. +Error +messages supplement return codes by describing in more detail what went +wrong. Debug messages are useful when debugging librsync or applications +that call it. + +These +follow a fairly standard priority-based filtering system +(rs_trace_set_level()), using the same severity levels as UNIX syslog. +Messages by default are sent to stderr, but may be passed to an +application-provided callback (rs_trace_to(), rs_trace_fn_t()). + +The default configuration is that warning and error messages are written +to stderr. This should be appropriate for many applications. If it is +not, the level and destination of messages may be changed. + +Messages are passed out of librsync through a trace callback which is +passed a severity and message string. The type for this callback is +\ref rs_trace_fn_t. + +The default trace function is \ref rs_trace_stderr. + +The trace callback may be changed at runtime with \ref rs_trace_to. + +Messages from librsync are labelled with a severity indicator of +enumerated type \ref rs_loglevel. + +The application may also specify a minimum severity of interest through +\ref rs_trace_set_level. +Messages lower than the specified level +are discarded without being passed to the trace callback. |