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
|
.\"
.\" -*- nroff -*-
.\"
.\" Copyright (c) 2002-2004 Abraham vd Merwe <abz@blio.com>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the author nor the names of other contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
.\" THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.TH LOG_OPEN 3debug "August 2004" Unix "Library calls"
.SH NAME
log_open, log_close, log_reset, log_flush, log_printf, log_vprintf, log_putc, log_puts - log routines for debugging
.SH LIBRARIES
Debug Library (\-ldebug)
.SH SYNOPSIS
.nf
.B #include <debug/log.h>
.sp
.BI "int log_open(const char *" logfile ", int " level ", int " flags ");
.br
.BI "void log_close(void);
.br
.BI "int log_reset(void);
.br
.BI "int log_flush(void);
.br
.BI "int log_printf(int " level ", const char *" fmt ", ...);
.br
.BI "int log_vprintf(int " level ", const char *" fmt ", va_list " ap ");
.br
.BI "int log_putc(int " level ", int " c ");
.br
.BI "int log_puts(int " level ", const char *" str ");
.fi
.SH DESCRIPTION
\fBlog_open()\fP initializes the logging system. The filename of the file to
which messages are logged should be specified by \fIlogfile\fP, or
\fBNULL\fP if messages should be printed to the console. The values for
\fIlevel\fP and \fIflags\fP are given in the next section.
.PP
From version 0.4.1 onwards the debug library also supports logging to syslog
instead of a file. Instead of specifying a file, just specify a string in
the form \fIident.facility\fP, where \fIident\fP is a string which will be
prepended to each syslog message and is usually the program name. The
\fIfacility\fP should be the facility to which messages should be logged.
.PP
\fBlog_close()\fP flushes all pending messages, and closes the file descriptor
of the log file (if any).
.PP
\fBlog_reset()\fP reinitializes the logging system. If any files are
currently opened for writing, it will be closed and reopened. This is useful
if you need to rotate log files.
.PP
\fBlog_flush()\fP flushes all pending messages (if any).
.PP
\fBlog_printf()\fP and \fBlog_vprintf()\fP are replacements for
\fBprintf\fP(3) and \fBvprintf\fP(3) respectively.
.PP
\fBlog_putc()\fP will log a single character. This is the equivalent of
\fBputchar\fP(3).
.PP
\fBlog_puts()\fP will log a string. It is the equivalent of \fBputs\fP(3),
except that is does not append a trailing newline.
.SH PARAMETERS
This section lists the parameters used to set the values of \fIlevel\fP and
\fIflags\fP.
.SS level
This determines the importance of the message. The levels are, in order of
decreasing verbosity:
.TP
.B LOG_NOISY
verbose debug messages
.TP
.B LOG_DEBUG
debug messages
.TP
.B LOG_VERBOSE
informational messages
.TP
.B LOG_NORMAL
normal, but significant, conditions
.TP
.B LOG_WARNING
warning conditions
.TP
.B LOG_ERROR
error conditions
.TP
.B LOG_QUIET
no messages are printed
.PP
The \fIlevel\fP argument to \fBlog_printf()\fP, \fBlog_vprintf()\fP,
\fBlog_putc()\fP, and \fBlog_puts()\fP specify the level at which the
message should be printed. It does not make sense to specify \fBLOG_QUIET\fP
to these functions.
.PP
The \fIlevel\fP argument to \fBlog_open()\fP sets the verbosity of the
program. Any messages printed with a \fIlevel\fP higher (more verbose) than
that specified to the \fBlog_open()\fP function, will be discarded.
.SS flags
The \fIflags\fP argument to \fBlog_open()\fP is an OR of any of these:
.TP
.B LOG_HAVE_COLORS
If this flag is specified and messages are printed to the console (i.e. no
log file is specified), messages will be printed in different colors,
depending on their log level.
.TP
.B LOG_PRINT_FUNCTION
If this flag is specified, the function in which the print function was
called would be printed in addition to the filename and line number.
.TP
.B LOG_DEBUG_PREFIX_ONLY
If this flag is specified, only messages with a level higher or equal to
(i.e. more or as verbose) \fBLOG_DEBUG\fP will be printed in color and with
file, line number, and (if necessary), the function.
.TP
.B LOG_DETECT_DUPLICATES
If this flag is specified, messages would be buffered and duplicate lines
would not be printed. Instead, the first message would be printed, followed
by a line describing the number of times the message repeated. This is a
great way to prevent flooding, but unfortunately it has the side effect of
always being one statement behind.
.TP
.B LOG_DETECT_FLOODING
If specified, the rate at which messages are printed would be limited in
order to avoid flooding. This feature have not been implemented yet, and is
currently ignored.
.SH RETURN VALUE
All functions except \fBlog_close()\fP return 0 if successful, \-1 if some
error occurred. Check errno to see which error occurred.
.PP
If \fBlog_reset()\fP or \fBlog_open()\fP fails, behaviour is undefined and
it should be assumed that no logging is possible.
.PP
The \fBlog_close()\fP function returns no value.
.SH "NOTES"
If this routines are combined with the memory routines, care should be taken
to call open and close functions in the right order. The correct order is as
follows:
.RS
.nf
.ta 4n 11n 17n
mem_open (NULL);
log_open (NULL,LOG_NORMAL,LOG_HAVE_COLORS | LOG_PRINT_FUNCTION);
atexit (mem_close);
atexit (log_close);
.fi
.RE
Of course, \fBatexit\fP(3) should only be used if the program will not
forked.
.PP
None of the libdebug routines are thread-safe. I'm not planning to change this
either! For more information, please see http://threading.2038bug.com/
.SH "SEE ALSO"
mem_open(3), errno(3), atexit(3), printf(3), vprintf(3), putchar(3), puts(3)
.br
logrotate(8), syslog(3), logger(1)
.SH "AUTHOR"
Written by Abraham vd Merwe <abz@blio.com>
|
