1
.\"(c) Copyright 1992, 1993 by Panagiotis Tsirigotis
2
.\"All rights reserved. The file named COPYRIGHT specifies the terms
3
.\"and conditions for redistribution.
5
.\" $Id: xlog.3,v 1.1.1.1 2003/02/19 17:29:27 bbraun Exp $
6
.TH XLOG 3X "15 June 1993"
7
xlog_parms, xlog_create, xlog_destroy, xlog_write, xlog_control -- general purpose logging facility
15
xlog_h xlog_create( type, id, flags, ... )
21
int xlog_parms( type, ... )
25
void xlog_destroy( xlog )
29
void xlog_write( xlog, buf, len, flags, ... )
36
int xlog_control( xlog, cmd, ... )
40
The purpose of this library is to provide a general purpose logging facility
43
logging objects that may be connected to various existent logging facilities.
44
Currently, the only logging facilities supported are
47
Log entries are timestamped lines which may contain arbitrary information.
48
.\" ********************* xlog_create ***********************
51
creates a new xlog of the specified
53
Possible type values are:
57
Varargs: \fIint facility, int priority\fP.
58
The xlog will be connected to
61
determines the syslog facility to use for logged messages and
63
is the default message priority.
66
Varargs: \fIchar *pathname, int flags [, int flags]\fP.
67
The xlog will be connected to the file identified by
69
The variable part of the argument list has the same semantics as the
75
All xlogs have an id, specified by the
79
argument is formed by ORing one or more of the following constants:
85
with an explanation of the current value of errno.
88
.I "(XLOG_FILELOG only)"
89
do not perform size checks on the file.
92
precede each log entry with the xlog id
95
precede each log entry with the process id
96
(the process id will follow the xlog id)
99
Flags that do not apply to the xlog are ignored.
102
can be used if you don't want to specify any flags.
103
.\" ********************* xlog_parms ***********************
106
sets default parameters for the specified xlog
111
3 arguments are expected which correspond one-to-one to the arguments of
113
The defaults, in case this function is not used, are:
114
"XLOG", LOG_PID + LOG_NOWAIT, LOG_USER
121
should be invoked before any xlogs of the specified type
123
.\" ********************* xlog_destroy ***********************
126
destroys an xlog. The action taken depends on the type of the xlog:
130
if this is the last xlog using syslog, then
137
.\" ********************* xlog_control ***********************
140
applies control operations to an xlog. Certain operations are common to
141
all xlogs while others are type-specific. The common ones are:
145
Argument list: \fIxlog_h link_to\fP.
146
Link the specified xlog to the one provided as argument.
149
any existent link is severed).
150
Linking xlogs has the effect that if one finds an error it uses the
154
Argument list: \fIvoid (*callback)(), void *arg\fP.
155
This function will be invoked in case of error while writing a log
156
entry. It will be given
157
3 arguments: the xlog handle, an integer that indicates the type
160
specified in this call. Possible errors include:
179
Argument list: \fIint flag, int *value\fP.
182
(one of those listed before) is set according to
184
which should be either 0 or 1.
185
The old flag value is placed in
189
Argument list: \fIint flag, int *value\fP.
192
(one of those listed before) is placed in
198
also support the following operations:
202
Argument list: \fIint facility\fP.
203
Sets the syslog facility to the specified value.
206
Argument list: \fIint level\fP.
207
Sets the default syslog level for this xlog to the specified value.
210
Argument list: \fIvoid\fP.
211
Prepares the xlog for an impending exec operation
214
Argument list: \fIvoid\fP.
215
Informs the xlog that the exec failed
220
also support the following operations:
224
Argument list: \fIunsigned soft_limit, unsigned hard_limit\fP.
225
Sets soft and hard limits on the size of the file.
226
When any of the limits is exceeded a message is sent to the linked xlog.
227
(if there is no linked xlog, no message is sent)
228
When the soft limit is exceeded a warning message is sent to the linked xlog
229
(if the linked xlog is of the
231
type, the message will be sent at the
234
If the exceeded limit is the hard limit, logging is terminated.
235
The actual file size is checked every time this operation is applied to
237
If logging was terminated because the hard limit was exceeded and
238
this operation increases the hard limit beyond the actual file size,
239
logging will be resumed.
242
Argument list: \fIvoid\fP.
243
Checks the actual file size.
246
Argument list: \fIint *value\fP.
249
the file descriptor of the log file.
251
.\" ********************* xlog_write ***********************
254
writes a message to the specified xlog. A
256
is always appended to the message.
257
The first occurrence of "%m" in
259
is replaced by a string explaining the current value of
263
argument is formed in the same way as in
265
One additional constant is available:
269
.I "(XLOG_SYSLOG only)"
270
the next argument is an integer that should be used as the syslog level
271
for this message instead of the default level of the xlog.
275
returns an xlog handle or
280
returns an error code (it returns
282
if it is successful).
285
returns an error code (it returns
287
if it is successful).
289
openlog(3), syslog(3), closelog(3)
292
Only the first occurrence of
294
is replaced by an errno explanation.
296
There is no check for cycles when linking xlogs. In particular it is
297
possible to link a xlog to itself.
added
removed
libs/src/xlog/xlog.3
