Add doxygen-style comments to document macros, and an overview
[OpenSRF.git] / include / opensrf / log.h
1 #ifndef OSRF_LOG_INCLUDED
2 #define OSRF_LOG_INCLUDED
3
4 /**
5         @file log.h
6         @brief Header for logging routines.
7
8         The OSRF logging routines support five different levels of log messages, and route them
9         to any of three kinds of destinations.  Utility routines are available to control various
10         details.
11
12         The message levels are as follows:
13
14         - OSRF_LOG_ERROR for error messages
15         - OSRF_LOG_WARNING for warning messages
16         - OSRF_LOG_INFO for informational messages
17         - OSRF_LOG_DEBUG for debug messages
18         - OSRF_LOG_INTERNAL for internal messages
19
20         The application can set a message level so as to suppress some of the messages.
21         Each level includes the ones above it.  For example, if the message level is set to
22         OSRF_LOG_INFO, then the logging routines will issue error messages, warning messages, and
23         informational messages, but suppress debug messages and internal messages.
24
25         There are also activity messages, which are similar to informational messages, but can be
26         enabled or disabled separately.
27
28         The messages may be written to standard error (the default), to a designated log file, or
29         to the Syslog (see man syslog).  In the latter case, the application can specify a facility
30         number in order to control what Syslog does with the messages.  The facility number for
31         activity numbers is controlled separately from that of the other message types.
32
33         The messages are formatted like the following example:
34
35         srfsh 2009-10-09 15:58:23 [DEBG:10530:socket_bundle.c:394:] removing socket 5
36
37         The message includes:
38
39         -# An application name
40         -# A time stamp
41         -# A tag indicating the message level
42         -# The file name and line number from whence the message was issued
43         -# An optional transaction id (not present in this example)
44         -# The message text, formatted using printf-style conventions
45 */
46
47 #include <opensrf/utils.h>
48
49 #include <syslog.h>
50 #include <stdio.h>
51 #include <time.h>
52 #include <errno.h>
53
54 #ifdef __cplusplus
55 extern "C" {
56 #endif
57
58 /* log levels */
59 #define OSRF_LOG_ERROR 1        /**< Level for error messages */
60 #define OSRF_LOG_WARNING 2      /**< Level for warning messages */
61 #define OSRF_LOG_INFO 3         /**< Level for informational messages */
62 #define OSRF_LOG_DEBUG 4        /**< Level for debug messages */
63 #define OSRF_LOG_INTERNAL 5     /**< Level for internal messages */
64 #define OSRF_LOG_ACTIVITY -1    /**< Pseudo message level for activity messages */
65
66 #define OSRF_LOG_TYPE_FILE 1    /**< Direct messages to a log file */
67 #define OSRF_LOG_TYPE_SYSLOG 2  /**< Direct messages to Syslog */
68 #define OSRF_LOG_TYPE_STDERR 3  /**< Direct messages to standard error */
69
70 /**
71         Convenience macro for passing source file name and line number
72         to the logging routines
73 */
74 #define OSRF_LOG_MARK __FILE__, __LINE__
75
76 void osrfLogInit( int type, const char* appname, int maxlevel );
77
78 void osrfLogSetSyslogFacility( int facility );
79
80 void osrfLogSetSyslogActFacility( int facility );
81
82 void osrfLogToStderr( void );
83
84 void osrfRestoreLogType( void );
85
86 void osrfLogSetFile( const char* logfile );
87
88 void osrfLogSetAppname( const char* appname );
89
90 void osrfLogSetLevel( int loglevel );
91
92 int osrfLogGetLevel( void );
93
94 void osrfLogError( const char* file, int line, const char* msg, ... );
95
96 void osrfLogWarning( const char* file, int line, const char* msg, ... );
97
98 void osrfLogInfo( const char* file, int line, const char* msg, ... );
99
100 void osrfLogDebug( const char* file, int line, const char* msg, ... );
101
102 void osrfLogInternal( const char* file, int line, const char* msg, ... );
103
104 void osrfLogActivity( const char* file, int line, const char* msg, ... );
105
106 void osrfLogCleanup( void );
107
108 void osrfLogClearXid( void );
109
110 void osrfLogSetXid(char* xid);
111
112 void osrfLogForceXid(char* xid);
113
114 void osrfLogMkXid( void );
115
116 void osrfLogSetIsClient(int is);
117
118 const char* osrfLogGetXid( void );
119
120 void osrfLogSetActivityEnabled( int enabled );
121
122 int osrfLogFacilityToInt( const char* facility );
123
124 #ifdef __cplusplus
125 }
126 #endif
127
128 #endif