51
52
.SH Declaration of the System logger
52
53
The logsys library is initially configured by including logsys.h and declaring
53
a logger. Once the logger is declared either a subsystem logger or nosubsystem
54
logger is declared in every file.
54
a logger. Once the logger is declared, optional subsystem loggers can be
55
declared in every file.
56
57
The definition LOGSYS_DECLARE_SYSTEM is placed after the include section of one
57
58
C file in the application. This declaration creates a constructor function
58
which will be called automatically. This technique avoids the need for calling
59
any setup functions in short applications that don't require it.
61
#define LOGSYS_DECLARE_SYSTEM(name,mode,file,facility)
62
The name parameter is the name of the application.
63
The mode parameter is the logging mode of the system. The following modes
64
can be configured by logically ORing these flags:
65
LOG_MODE_OUTPUT_FILE: Output all log data to the file parameter of this declaration
66
LOG_MODE_OUTPUT_STDERR: Output all log data to the stderr descriptor
67
LOG_MODE_OUTPUT_SYSLOG_THREADED: Output all log data to syslog using a non-blocking thread
68
LOG_MODE_OUTPUT_SYSLOG_LOSSY: Output all log data without using a thread but potentially losing data. This mode is not yet implemented.
69
LOG_MODE_OUTPUT_SYSLOG_BLOCKING: Output all log data without using a thread and potentially blocking at each syslog call.
70
LOG_MODE_DISPLAY_PRIORITY: Output the priority of the log entry in the message contents. This mode is currently not implemented.
71
LOG_MODE_DISPLAY_FILELINE: Output the file and line at which the log message was created.
72
LOG_MODE_SHORT_FILELINE: When using LOG_DEBUG level or LOG_MODE_DISPLAY_FILELINE, typically the absolute path to the file (derived at compile-time) is displayed. Enabling this flag ensures that only the filename and line are displayed.
73
LOG_MODE_DISPLAY_TIMESTAMP: Output the timestamp of the message.
74
LOG_MODE_BUFFER_BEFORE_CONFIG: This mode is used to buffer log messages before logsys_mode_config is called. This is useful in applications in which the logging file isn't known before the application is compiled and must be set dynamically. It is also useful when an application calls fork to disconnect the local tty and should hold logging of messages until after the fork.
75
LOG_MODE_FLUSH_AFTER_CONFIG: This mode is used to flush any buffered messages when the LOG_MODE_BUFFER_BEFORE_CONFIG declaration is specified in the declaration of the logger.
76
The file parameter specifies the filename that should be used to log messages. This parameter may be NULL if LOG_MODE_OUTPUT_FILE is not specified.
77
The facility parameter is the syslog facility that should be used when logging
59
which will be called automatically before main() is executed. This technique
60
avoids the need for calling any setup functions in short applications that don't
61
require it and enables full logging capabilities before any application code is
64
#define LOGSYS_DECLARE_SYSTEM (name, mode, debug, file, file_priority,
65
syslog_facility, syslog_priority, format, fltsize)
67
The name parameter is the name of the application or system.
69
The mode parameter is the logging mode of the system.
70
The following modes can be configured by logically ORing these flags:
72
LOGSYS_MODE_OUTPUT_FILE: Output all log data to the file parameter of this declaration
74
LOGSYS_MODE_OUTPUT_STDERR: Output all log data to the stderr descriptor
76
LOGSYS_MODE_OUTPUT_SYSLOG: Output all log data to syslog using a non-blocking thread
78
LOGSYS_MODE_FORK: This flags tells logsys to queue all data untill the application
79
has forked. The application is then responsible to call logsys_fork_completed to flush
80
the queue and start logging.
82
LOGSYS_MODE_THREADED: Starts a separate thread to handle non-blocking logging operations.
83
If this flag is not specified, the logging operations are blocking.
85
The debug parameter, if enabled, turns off all messages priority filtering, recording
86
everything everywhere.
88
The file parameter specifies the filename that should be used to log messages.
89
This parameter may be NULL and no log file will be created.
91
The file_priority parameter specifies the message priority that should be logged to file.
93
The syslog_facility parameter is the syslog facility that should be used when logging
79
LOG_MODE_NOSUBSYS: Enabling this mode removes the subsystem tag from the beginning of the log lines. This is not recommended for programs which have multiple subsystems.
80
LOG_MODE_FILTER_DEBUG_FROM_SYSLOG: Enabling this mode will stop debug messages from being sent to syslog.
96
The syslog_priority, similar to file_priority, specifies the message priority that should be logged to
99
The format parameter allows to set custom output format.
100
Set to NULL to use built-in default.
102
The fltsize parameter specifies the flight recorder buffer size in bytes. The requested value
103
is increased by the size of 2 unsigned ints and rounded to the next PAGE_SIZE.
82
105
An example declaration would be:
86
109
... (other #includes)
88
LOGSYS_DECLARE_SYSTEM ("my_example_app",
89
LOG_MODE_OUTPUT_STDERR | LOG_MODE_OUTPUT_SYSLOG_THREADED | LOG_MODE_OUTPUT_FILE,
93
This would output any logging messages to stderr, syslog, and the file /tmp/log.
95
.SH Declaration of subsystems or no subsystems
111
LOGSYS_DECLARE_SYSTEM ("test", /* name */
112
LOGSYS_MODE_OUTPUT_STDERR | LOGSYS_MODE_THREADED, /* mode */
114
NULL, /* logfile path */
115
LOGSYS_LEVEL_INFO, /* logfile_priority */
116
LOG_DAEMON, /* syslog facility */
117
LOGSYS_LEVEL_INFO, /* syslog level */
118
NULL, /* use default format */
119
1000000); /* flight recorder size */
122
.SH Declaration of subsystems
96
123
The logsys library supports the logging of information to one main system or
97
subsystem. This is specified in each individual object file in the system.
99
if no subsystems are desired, The define LOGSYS_DECLARE_NOSUBSYS should be
100
declared for every object file in the system. These object files are usually C
103
An example of using this would be
105
LOGSYS_DECLARE_NOSUBSYS (LOG_LEVEL_INFO);
107
Any messages of LOG_LEVEL_INFO priority or higher would be logged.
109
If subsystems are desired, the define LOGSYS_DECLARE_SUBSYS should be declared
110
for every object file in the system. It is possible to use the same subsystem
111
name in separate object files. In this case, the individual logging parameters
112
for those subsystem identifier will be used.
114
An example of using this would be
115
LOGSYS_DECLARE_SUBSYS ("SYS1", LOG_LEVEL_INFO);
117
Any message of LOG_LEVEL_INFO priority or higher would be logged and any
118
logging within the object file this declaration is specified within will be
119
logged to the SYS1 subsystem identifier.
124
subsystem. This is specified in each individual object C file in the system
125
and it is entirely optional.
129
LOGSYS_DECLARE_SUBSYS ("subsystest");
131
It is possible to use the same subsystem name in separate object files.
132
In this case, the individual logging parameters for those subsystem identifier
135
A newly created subsystem inherits the system configuration at the time of
138
It is possible to override every configuration option on a subsystem base
139
throught the configuration API.
121
141
.SH Logging Messages
122
142
The definition log_printf is used to log information to the log. It works
123
143
in a similiar fashion to printf, except it has a first parameter of level
124
144
which may be the following:
134
154
An example of using log_printf would be
136
log_printf (LOG_EMERG, "This is an emergency %s value %d\n", string, value);
138
Tracing of functions can be done using ENTER_VOID() or ENTER (format, args) LEAVE_VOID() or LEAVE (format, args);
140
An exmaple of using ENTER_VOID is
141
void funtion (void) {
143
... function contents ...
147
An example of using ENTER is
156
log_printf (LOGSYS_LEVEL_EMERG, "This is an emergency %s value %d\n", string, value);
158
Tracing of functions can be done using ENTER(), LEAVE();
160
An example of using ENTER is
148
161
void function (char *name) {
149
ENTER ("The name is %s\n", name);
150
163
... function contents ...
154
167
Individual tracing levels are supported through the macros
162
175
char *name = "test";
163
176
TRACE7 ("This is a trace 7 log with name %s\n", name);
178
Note that ENTER/LEAVE/TRACE* calls are recorded only in the flight recorder.
166
.BR logsys_config_mode_set (3),
167
.BR logsys_config_file_set (3),
168
.BR logsys_config_facility_set (3),
169
.BR logsys_config_facility_set (3),
170
.BR logsys_config_priority_set (3),
171
.BR logsys_config_subsys_set (3),
172
.BR logsys_config_subsys_get (3),
181
.BR logsys_fork_completed (3),
182
.BR logsys_atexit (3),
183
.BR logsys_log_rec_store (3),
184
.BR logsys_format_set (3),
185
.BR logsys_format_get (3),
186
.BR logsys_config_mode_set (3),
187
.BR logsys_config_file_set (3),
188
.BR logsys_config_syslog_facility_set (3),
189
.BR logsys_config_syslog_facility_get (3),
190
.BR logsys_config_mode_set (3),
191
.BR logsys_config_mode_get (3),
192
.BR logsys_config_file_set (3),
193
.BR logsys_config_logfile_priority_set (3),
194
.BR logsys_config_debug_set (3),
173
195
.BR logsys_facility_id_get (3),
196
.BR logsys_facility_name_get (3),
174
197
.BR logsys_priority_id_get (3),
175
.BR logsys_flush (3),
176
.BR logsys_atsegv (3),
198
.BR logsys_priority_name_get (3),
added
removed
man/logsys_overview.8
