Commit bc0b85e4 authored by Pekka Pessi's avatar Pekka Pessi

su: updated documentation of debugging logs.

darcs-hash:20061009154955-65a35-a3904acd5038f0609a99c8bf8f703351e4c410cb.gz
parent a451bb91
......@@ -7,6 +7,7 @@ INPUT = su.docs sofia-sip .
TAGFILES += ../docs/msg.doxytags=../msg
TAGFILES += ../docs/sip.doxytags=../sip
TAGFILES += ../docs/docs.doxytags=..
GENERATE_TAGFILE = ../docs/su.doxytags
......
......@@ -31,20 +31,23 @@
* @brief SU debugging macros
*
* The logging levels and macros to use are defined as follows:
* - su_log() fatal errors, panic
* - SU_DEBUG_0() critical errors, minimal progress at subsystem level
* - SU_DEBUG_1() non-critical errors
* - SU_DEBUG_0() fatal errors, panic
* - SU_DEBUG_1() critical errors, minimal progress at subsystem level
* - SU_DEBUG_2() non-critical errors
* - SU_DEBUG_3() warnings, progress messages
* - SU_DEBUG_5() signaling protocol actions (incoming packets, etc.)
* - SU_DEBUG_7() media protocol actions (incoming packets, etc.)
* - SU_DEBUG_9() entering/exiting functions, very verbatim progress
*
* Module-specific logging requires redefining SU_LOG macro with a pointer
* to a su_log_t variable.
* These macros are used to log with module-specific levels. The SU_LOG
* macro is redefined with a pointer to a module-specific #su_log_t
* structure, e.g., "iptsec_debug.h".
*
* @author Pekka Pessi <Pekka.Pessi@nokia.com>
*
* @date Created: Tue Feb 8 10:06:33 2000 ppessi
*
* @sa @ref debug_logs, su_llog(), su_vllog(), #su_log_t,
*/
#ifndef SU_LOG_H
......@@ -77,7 +80,12 @@ SOFIAPUBVAR su_log_t SU_LOG[];
{ va_list ap; va_start(ap, fmt); su_vllog(SU_LOG, level, fmt, ap); va_end(ap); }
SU_DEBUG_DEF(0)
/** Log critical errors, minimal progress at subsystem level. */
/** Log messages at level 0.
*
* Fatal errors and panic messages should be logged at level 0.
*
* @sa su_llog(), su_vllog(), #su_log_t, @ref debug_logs
*/
#define SU_DEBUG_0(x) (SU_LOG_LEVEL >= 0 ? (su_debug_0 x) : (void)0)
/** Log C library errors. */
......@@ -93,7 +101,13 @@ SU_DEBUG_DEF(0)
#if SU_DEBUG_MAX >= 1
SU_DEBUG_DEF(1)
/** Log non-critical errors. */
/**Log messages at level 1.
*
* Critical errors and minimal progress at subsystem level should be logged
* at level 1.
*
* @sa su_llog(), su_vllog(), #su_log_t, @ref debug_logs
*/
#define SU_DEBUG_1(x) (SU_LOG_LEVEL >= 1 ? (su_debug_1 x) : (void)0)
#else
#define SU_DEBUG_1(x) (void)1
......@@ -101,7 +115,12 @@ SU_DEBUG_DEF(1)
#if SU_DEBUG_MAX >= 2
SU_DEBUG_DEF(2)
/** Log messages at level 2. */
/**Log messages at level 2.
*
* Non-critical errors should be logged at level 2.
*
* @sa su_llog(), su_vllog(), #su_log_t, @ref debug_logs
*/
#define SU_DEBUG_2(x) (SU_LOG_LEVEL >= 2 ? (su_debug_2 x) : (void)0)
#else
#define SU_DEBUG_2(x) (void)2
......@@ -109,7 +128,12 @@ SU_DEBUG_DEF(2)
#if SU_DEBUG_MAX >= 3
SU_DEBUG_DEF(3)
/** Log warnings, progress messages. */
/** Log messages at level 3.
*
* Warnings and progress messages should be logged at level 3.
*
* @sa su_llog(), su_vllog(), #su_log_t, @ref debug_logs
*/
#define SU_DEBUG_3(x) (SU_LOG_LEVEL >= 3 ? (su_debug_3 x) : (void)0)
#else
#define SU_DEBUG_3(x) (void)3
......@@ -125,7 +149,13 @@ SU_DEBUG_DEF(4)
#if SU_DEBUG_MAX >= 5
SU_DEBUG_DEF(5)
/** Log signaling protocol actions (incoming packets, etc.). */
/** Log messages at level 5.
*
* Signaling protocol actions (incoming packets, etc.) should be logged
* at level 5.
*
* @sa su_llog(), su_vllog(), #su_log_t, @ref debug_logs
*/
#define SU_DEBUG_5(x) (SU_LOG_LEVEL >= 5 ? (su_debug_5 x) : (void)0)
#else
#define SU_DEBUG_5(x) (void)5
......@@ -141,7 +171,12 @@ SU_DEBUG_DEF(6)
#if SU_DEBUG_MAX >= 7
SU_DEBUG_DEF(7)
/** Log media protocol actions (incoming packets, etc.). */
/** Log messages at level 7.
*
* Media protocol actions (incoming packets, etc) should be logged at level 7.
*
* @sa su_llog(), su_vllog(), #su_log_t, @ref debug_logs
*/
#define SU_DEBUG_7(x) (SU_LOG_LEVEL >= 7 ? (su_debug_7 x) : (void)0)
#else
#define SU_DEBUG_7(x) (void)7
......@@ -157,7 +192,13 @@ SU_DEBUG_DEF(8)
#if SU_DEBUG_MAX >= 9
SU_DEBUG_DEF(9)
/** Log entering/exiting functions, very verbatim progress. */
/** Log messages at level 9.
*
* Entering/exiting functions, very verbatim progress should be logged at
* level 9.
*
* @sa su_llog(), su_vllog(), #su_log_t, @ref debug_logs
*/
#define SU_DEBUG_9(x) (SU_LOG_LEVEL >= 9 ? (su_debug_9 x) : (void)0)
#else
#define SU_DEBUG_9(x) (void)9
......
......@@ -52,7 +52,7 @@ typedef struct su_log_s su_log_t;
SOFIA_BEGIN_DECLS
/**Prototype for logging function */
/** Prototype for logging function */
typedef void (su_logger_f)(void *stream, char const *fmt, va_list ap);
/** Log object. */
......
......@@ -22,11 +22,12 @@
*
*/
#ifndef SU_OSX_RUNLOOP_H /** Defined when su_source.h has been included. */
#ifndef SU_OSX_RUNLOOP_H
/** Defined when <sofia-sip/su_osx_runloop.h> has been included. */
#define SU_OSX_RUNLOOP_H
/**
* @file su_source.h
* @file sofia-sip/su_osx_runloop.h
* @brief
*
* @author Martti Mela <Martti.Mela@nokia.com>
......@@ -43,8 +44,8 @@
SOFIA_BEGIN_DECLS
su_root_t *su_root_osx_runloop_create(su_root_magic_t *) __attribute__((__malloc__));
/* GSource *su_root_source(su_root_t *); */
su_root_t *su_root_osx_runloop_create(su_root_magic_t *)
__attribute__((__malloc__));
SOFIA_END_DECLS
......
......@@ -99,15 +99,6 @@
* - #su_iovec_t: structure holding scatter-gather IO vector
*/
/**@defgroup su_log Logging Interface
*
* Generic logging interface.
*
* The @b su_log submodule contains a generic logging interface. The
* interface provides means for redirecting the log and filtering log
* messages based on message priority.
*/
/**@defgroup su_htable Hash tables
*
* Hash tables.
......
......@@ -54,11 +54,27 @@
#define SU_LOG_UNLOCK(log)
#endif
/**@defgroup su_log Logging Interface
*
* Generic logging interface.
*
* The @b su_log submodule contains a generic logging interface. The
* interface provides means for redirecting the log and filtering log
* messages based on message priority.
*
* @sa @ref debug_logs, <sofia-sip/su_log.h>,
* su_llog(), su_vllog(), #su_log_t, #SU_LOG,
* SU_DEBUG_0(), SU_DEBUG_1(), SU_DEBUG_2(), SU_DEBUG_3(), SU_DEBUG_5(),
* SU_DEBUG_7(), SU_DEBUG_9()
*/
/** Log message of socket error @errcode at level 0. */
void su_perror2(const char *s, int errcode)
{
su_log("%s: %s\n", s, su_strerror(errcode));
}
/** Log socket error message at level 0. */
void su_perror(const char *s)
{
su_perror2(s, su_errno());
......
......@@ -188,7 +188,7 @@ su_port_vtable_t const su_port_osx_vtable[1] =
static int su_port_osx_wait_events(su_port_t *self, su_duration_t tout);
/**
/* *
* Port is a per-thread reactor.
*
* Multiple root objects executed by single thread share a su_port_t object.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment