libs/src/xlog/xlog.3

   1 .\"(c) Copyright 1992, 1993 by Panagiotis Tsirigotis
   2 .\"All rights reserved.  The file named COPYRIGHT specifies the terms
   3 .\"and conditions for redistribution.
   4 .\"
   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
   8 .SH SYNOPSIS
   9 .LP
  10 .nf
  11 .ft B
  12 #include "xlog.h"
  13 .LP
  14 .ft B
  15 xlog_h xlog_create( type, id, flags, ... )
  16 xlog_e type ;
  17 char *id ;
  18 int flags ;
  19 .LP
  20 .ft B
  21 int xlog_parms( type, ... )
  22 xlog_e type ;
  23 .LP
  24 .ft B
  25 void xlog_destroy( xlog )
  26 xlog_h xlog ;
  27 .LP
  28 .ft B
  29 void xlog_write( xlog, buf, len, flags, ... )
  30 xlog_h xlog ;
  31 char buf[] ;
  32 int len ;
  33 int flags ;
  34 .LP
  35 .ft B
  36 int xlog_control( xlog, cmd, ... )
  37 xlog_h xlog ;
  38 xlog_cmd_e cmd ;
  39 .SH DESCRIPTION
  40 The purpose of this library is to provide a general purpose logging facility
  41 by providing
  42 .I xlogs,
  43 logging objects that may be connected to various existent logging facilities.
  44 Currently, the only logging facilities supported are
  45 .I "syslog(3)"
  46 and logging to files.
  47 Log entries are timestamped lines which may contain arbitrary information.
  48 .\" ********************* xlog_create ***********************
  49 .LP
  50 .B xlog_create()
  51 creates a new xlog of the specified
  52 .I type.
  53 Possible type values are:
  54 .RS
  55 .TP 20
  56 .SB XLOG_SYSLOG
  57 Varargs: \fIint facility, int priority\fP.
  58 The xlog will be connected to
  59 .I "syslog(3)."
  60 .I facility
  61 determines the syslog facility to use for logged messages and
  62 .I priority
  63 is the default message priority.
  64 .TP
  65 .SB XLOG_FILELOG
  66 Varargs: \fIchar *pathname, int flags [, int flags]\fP.
  67 The xlog will be connected to the file identified by
  68 .I pathname.
  69 The variable part of the argument list has the same semantics as the
  70 argument list of the
  71 .I "open(2)"
  72 system call.
  73 .RE
  74 .LP
  75 All xlogs have an id, specified by the
  76 .I id
  77 argument. The
  78 .I flags
  79 argument is formed by ORing one or more of the following constants:
  80 .RS
  81 .TP 20
  82 .SB XLOG_NO_ERRNO
  83 do not replace
  84 .I "%m"
  85 with an explanation of the current value of errno.
  86 .TP
  87 .SB XLOG_NO_SIZECHECK
  88 .I "(XLOG_FILELOG only)"
  89 do not perform size checks on the file.
  90 .TP
  91 .SB XLOG_PRINT_ID
  92 precede each log entry with the xlog id
  93 .TP
  94 .SB XLOG_PRINT_PID
  95 precede each log entry with the process id
  96 (the process id will follow the xlog id)
  97 .RE
  98 .LP
  99 Flags that do not apply to the xlog are ignored.
 100 The contant
 101 .SM XLOG_NOFLAGS
 102 can be used if you don't want to specify any flags.
 103 .\" ********************* xlog_parms ***********************
 104 .LP
 105 .B xlog_parms()
 106 sets default parameters for the specified xlog
 107 .I type:
 108 .RS
 109 .TP 20
 110 .SB XLOG_SYSLOG
 111 3 arguments are expected which correspond one-to-one to the arguments of
 112 .I "openlog(3)."
 113 The defaults, in case this function is not used, are:
 114 "XLOG", LOG_PID + LOG_NOWAIT, LOG_USER
 115 .TP
 116 .SB XLOG_FILELOG
 117 No action.
 118 .RE
 119 .LP
 120 .B xlog_parms()
 121 should be invoked before any xlogs of the specified type
 122 are created.
 123 .\" ********************* xlog_destroy ***********************
 124 .LP
 125 .B xlog_destroy()
 126 destroys an xlog. The action taken depends on the type of the xlog:
 127 .RS
 128 .TP 20
 129 .SB XLOG_SYSLOG
 130 if this is the last xlog using syslog, then
 131 .I "closelog(3)"
 132 is invoked.
 133 .TP
 134 .SB XLOG_FILELOG
 135 The file is closed.
 136 .RE
 137 .\" ********************* xlog_control ***********************
 138 .LP
 139 .B 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:
 142 .RS
 143 .TP 15
 144 .SB XLOG_LINK
 145 Argument list: \fIxlog_h link_to\fP.
 146 Link the specified xlog to the one provided as argument.
 147 (if the argument is
 148 .SM NULL
 149 any existent link is severed).
 150 Linking xlogs has the effect that if one finds an error it uses the
 151 other to report it.
 152 .TP
 153 .SB XLOG_CALLBACK
 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
 158 of error and the
 159 .I arg
 160 specified in this call. Possible errors include:
 161 .RS
 162 .TP 15
 163 .SB XLOG_ENOMEM
 164 lack of memory
 165 .TP
 166 .SB XLOG_EOPEN
 167 .I "open(2)"
 168 failed
 169 .TP
 170 .SB XLOG_EFSTAT
 171 .I "fstat(2)"
 172 failed
 173 .TP
 174 .SB XLOG_ESIZE
 175 hard limit exceeded
 176 .RE
 177 .TP
 178 .SB XLOG_SETFLAG
 179 Argument list: \fIint flag, int *value\fP.
 180 The value of
 181 .I flag
 182 (one of those listed before) is set according to
 183 .I "*value"
 184 which should be either 0 or 1.
 185 The old flag value is placed in
 186 .I "*value."
 187 .TP
 188 .SB XLOG_GETFLAG
 189 Argument list: \fIint flag, int *value\fP.
 190 The value of
 191 .I flag
 192 (one of those listed before) is placed in
 193 .I "*value."
 194 .RE
 195 .LP
 196 Xlogs of type
 197 .B XLOG_SYSLOG
 198 also support the following operations:
 199 .RS
 200 .TP 15
 201 .SB XLOG_FACILITY
 202 Argument list: \fIint facility\fP.
 203 Sets the syslog facility to the specified value.
 204 .TP
 205 .SB XLOG_LEVEL
 206 Argument list: \fIint level\fP.
 207 Sets the default syslog level for this xlog to the specified value.
 208 .TP
 209 .SB XLOG_PREEXEC
 210 Argument list: \fIvoid\fP.
 211 Prepares the xlog for an impending exec operation
 212 .TP
 213 .SB XLOG_POSTEXEC
 214 Argument list: \fIvoid\fP.
 215 Informs the xlog that the exec failed
 216 .RE
 217 .LP
 218 Xlogs of type
 219 .B XLOG_FILELOG
 220 also support the following operations:
 221 .RS
 222 .TP 15
 223 .SB XLOG_LIMITS
 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
 230 .SB XLOG_SYSLOG
 231 type, the message will be sent at the
 232 .I LOG_ALERT
 233 level).
 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
 236 the file.
 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.
 240 .TP
 241 .SB XLOG_SIZECHECK
 242 Argument list: \fIvoid\fP.
 243 Checks the actual file size.
 244 .TP
 245 .SB XLOG_GETFD
 246 Argument list: \fIint *value\fP.
 247 Places in
 248 .I "*value"
 249 the file descriptor of the log file.
 250 .RE
 251 .\" ********************* xlog_write ***********************
 252 .LP
 253 .B xlog_write()
 254 writes a message to the specified xlog. A
 255 .SM NEWLINE
 256 is always appended to the message.
 257 The first occurrence of "%m" in
 258 .I buf
 259 is replaced by a string explaining the current value of
 260 .I errno.
 261 The
 262 .I flags
 263 argument is formed in the same way as in
 264 .B xlog_create().
 265 One additional constant is available:
 266 .RS
 267 .TP 20
 268 .SB XLOG_SET_LEVEL
 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.
 272 .RE
 273 .SH "RETURN VALUES"
 274 .B xlog_create()
 275 returns an xlog handle or
 276 .SM NULL
 277 if it fails.
 278 .LP
 279 .B xlog_control()
 280 returns an error code (it returns
 281 .SM XLOG_ENOERROR
 282 if it is successful).
 283 .LP
 284 .B xlog_parms()
 285 returns an error code (it returns
 286 .SM XLOG_ENOERROR
 287 if it is successful).
 288 .SH "SEE ALSO"
 289 openlog(3), syslog(3), closelog(3)
 290 .SH BUGS
 291 .LP
 292 Only the first occurrence of
 293 .I "%m"
 294 is replaced by an errno explanation.
 295 .LP
 296 There is no check for cycles when linking xlogs. In particular it is
 297 possible to link a xlog to itself.