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.