1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
=============================================================================
The logger
This document explains the function and hence api of libatalk/util/logger.c
it was written on 4th January 2002, by Simon Bazley (sibaz@sibaz.com)
=============================================================================
The logger was written to provide a means of storing log messages relating to
netatalk in a file rather than using the syslog facility. The feature list
was increased to include a number of ideas culminating in the current code.
-----------------------------------------------------------------------------
Feature list
1) logging to syslog (old behaviour).
2) logging the file name and line number of the caller.
3) logging to a file.
4) allowing callers to specify what logical area of code the log comes from.
4) maintaining different log levels for different logical areas of code.
5) logging separate files for separate areas if required.
-----------------------------------------------------------------------------
Method
The logger works by storing an array of data containers each responsible for
logging to a single file.
Initally the array is initalised containing NULL references to the data,
except for the zeroth position with contains the defaults (default data is
statically defined in the logger code, but can be overridden easily).
As calls are made to the log_setup and syslog_setup functions with unused
code area references, new memory is allocated then a pointer to that memory
stored in the array. It is intended that all data containers are setup and
initialised early on in the program life cycle. There is no means to erase
initialised data containers other than by calling the log_close function,
which should only be done after the last log messages has been sent. Logger
behaviour is unspecified after log_close has been called.
=============================================================================
API Functions
=============================================================================
-----------------------------------------------------------------------------
void log_init();
Log_init allocates and zeros memory for the global data containers, then
sets up then copies the statically defined default loggers into the zero
position. It is called by both of the setup functions and will only do
anything if the global data hasn't already been initialised.
Its only made externally accessibly for completeness, and need never be used.
-----------------------------------------------------------------------------
bool log_setup(char *filename, enum loglevels loglevel,
enum logtypes logtype, int display_options);
log_setup specifies the filename and the loglevel that should be used when
logging logs with the specified logtype. The display_options indicate what
system stuff should be prepended to each line in the log file, in the same
way as the parameters in an openlog call. The options defined in the logger.h
file correspond to equivalents in the syslog.h file. The values they represent
are equivalent in both files, but should not be assumed.
Some logoptions not in syslog have been added, see logger.h for details.
-----------------------------------------------------------------------------
void syslog_setup(enum loglevels loglevel, enum logtypes logtype,
int display_options, int facility);
syslog_setup is equivalent to the log_setup call but setups data to log to the
syslogger for the area specified instead of a file. syslog_setup will call
openlog for each call to syslog_setup. The facility parameter is stored, but
used purely in this call to openlog. I assume it you call syslog_setup
multiple times with different values for display_options and facility, only the
last call is used. Refer to syslog(3) for more details.
The display options are global and are only stored once regardless of the
logtype. The value is only used by the logger used in-so-far-as the option is
not a feature of the syslogger.
The loglevel of the given logtype is stored even though the syslogger is used.
The loglevel passed to each call to LOG is translated before being sent to the
syslogger. The assumtion is that a log_severe (for example) applies only to
netatalk and hence should not be translated to LOG_CRIT, but instead LOG_ERR
is used. (this translation is implemented in the function at the end of the
logger.c file. This means should you want to you could log debug messages to
the syslogger without having to alter the syslogger for every other
application.
Some logoptions not in syslog have been added, see logger.h for details.
-----------------------------------------------------------------------------
void log_close();
log_close simply frees up all the memory and closes any open files. Ideally
you could then recall log_setup and start again, but I think its too permanent
for that. This also closes up the syslogger.
-----------------------------------------------------------------------------
void set_processname(char *processname);
set_processname stores the name of the funning process for use in identifying
the caller in each line in the log. This is equivalent to the parameter used
in the call to openlog, but since it is global for the process it seemed
sensible to separate it from every log_setup call.
-----------------------------------------------------------------------------
make_log_func set_log_location(char *srcfilename, int srclinenumber);
This sets up the temporary variables indicating the caller name and line number
logged in calls to make_log_entry. The return value is a pointer to the
make_log_entry function, thus enabling a single command to call both functions,
hidden behind a macro (the LOG macro, see later).
-----------------------------------------------------------------------------
void make_log_entry(enum loglevels loglevel, enum logtypes logtype,
char *message, ...);
make_log_entry is an equivalent function to syslog except for the logtype
parameter. The logtype given indicates which area of code the call has come
from and is used to determine which log_setup call is used to log the message.
-----------------------------------------------------------------------------
void load_proccessname_from_proc();
This function can be called instead of set_processname, to determine the
processname from the /proc file system instead of from a given parameter. This
probably only works on linux, but is included because it was the original
method used to get the procname.
-----------------------------------------------------------------------------
LOG Macro
This is actually defined as a call to set_log_location with parameters
__FILE__ and __LINE__. This returns a pointer to the make_log_entry function
which is then what the compiler will use to pass the given parameters to.
What this means on the face of it is the LOG Macro can be considered to be this
void LOG(enum loglevels loglevel, enum logtypes logtype,
char *message, ...);
-----------------------------------------------------------------------------
LogTypes
logtypes have been mentioned earlier. They specify the logical area of the
code that a log call has come from. This information is then used in a
number of ways (see earlier).
logtypes is infact an enum defined in the logger.h file. To add a new
logtype for a new area of code, add a new item to the logtypes enum, and a
corresponding string to the LOGTYPE_STRING_IDENTIFIERS macro.
The string identifier is used as part of the message string for each log
message.
=============================================================================
API in brief
=============================================================================
-----------------------------------------------------------------------------
SyslogSetup in brief
To setup the logger for use in a new application, call set_processname with
the proccess's name, then call syslog_setup with your prefered default loglevel
and the default logtype (logtype_default). The display_options and facility
are dependant on how you choose to display your logs.
For Example:
set_processname("afpd");
syslog_setup(log_debug, logtype_default, logoption_ndelay | logoption_pid,
logfacility_daemon);
this sets the default loglevel to debug and the display options to include the
pid with the each log message. The syslogger is told the application is of
type LOG_DAEMON
Make further calls to syslog_setup if other logtypes should have a different
loglevel.
-----------------------------------------------------------------------------
LogSetup in brief
Logsetup is similar to syslogsetup except multiple calls are more common.
First setup the filename and loglevel for the default logtype then call
log_setup with the filename and loglevel for any logtypes that should take
nondefault parameters. A NULL filename indicates that the default filename
should be used (this removes the need to store multiple instances of the same string).
For Example:
log_setup("/var/log/netatalk.log", log_debug, logtype_default,
logoption_ndelay | logoption_pid);
-----------------------------------------------------------------------------
Logging in brief
Logging is very similar to using the syslogger, just call the LOG macro in
your code with the level of that log message, and the area of code it applies
to (or logtype_default if you can't think of one), and a message. The message
is passed with identical parameters to that in an sprintf statement. Give a
format string as first parameter, then any variables in that string as extra
parameters.
The logger will only log the message if the loglevel given is more severe
(lower in value) than that given in the call to logsetup for the given logtype
(or default logtype if your given one is uninitialised).
For Example:
LOG(log_info, logtype_logger, "Logger %d setup complete", n);
|
