XLOG

SYNOPSIS

#include "xlog.h"

xlog_h xlog_create( type, id, flags, ... )
xlog_e type ;
char *id ;
int flags ;

int xlog_parms( type, ... )
xlog_e type ;

void xlog_destroy( xlog )
xlog_h xlog ;

void xlog_write( xlog, buf, len, flags, ... )
xlog_h xlog ;
char buf[] ;
int len ;
int flags ;

void xlog_control( xlog, cmd, ... )
xlog_h xlog ;
xlog_cmd_e cmd ;

DESCRIPTION

xlog_create() creates a new xlog of the specified type. Possible type values are:

XLOG_SYSLOG

Varargs: int facility, int priority. The xlog will be connected to syslog(3). facility determines the syslog facility to use for logged messages and priority is the default message priority.

XLOG_FILELOG

Varargs: char *pathname, int flags [, int flags]. The xlog will be connected to the file identified by pathname. The variable part of the argument list has the same semantics as the argument list of the open(2) system call.

All xlogs have an id, specified by the id argument. The flags argument is formed by ORing one or more of the following constants:

XLOG_NO_ERRNO

do not replace %m with an explanation of the current value of errno.

XLOG_NO_SIZECHECK

(XLOG_FILELOG only) do not perform size checks on the file.

XLOG_PRINT_TIMESTAMP

precede each log entry with a time stamp

XLOG_PRINT_ID

precede each log entry with the xlog id

XLOG_PRINT_PID

precede each log entry with the process id

Flags that do not apply to the xlog are ignored. The contant XLOG_NOFLAGS can be used if you don't want to specify any flags.

xlog_parms() sets default parameters for the specified xlog type:

XLOG_SYSLOG

3 arguments are expected which correspond one-to-one to the arguments of openlog(3). The defaults, in case this function is not used, are: "XLOG", LOG_PID + LOG_NOWAIT, LOG_USER

XLOG_FILELOG

No action.

xlog_parms() should be invoked before any xlogs of the specified type are created.

xlog_destroy() destroys an xlog. The action taken depends on the type of the xlog:

XLOG_SYSLOG

if this is the last xlog using syslog, then closelog(3) is invoked.

XLOG_FILELOG

The file is closed.

xlog_control() applies control operations to an xlog. Certain operations are common to all xlogs while others are type-specific. The common ones are:

XLOG_LINK

Argument list: xlog_h link_to. Link the specified xlog to the one provided as argument. (if the argument is NULL any existent link is severed). Linking xlogs has the effect that if one finds an error it uses the other to report it.

XLOG_CALLBACK

Argument list: void (*callback)(), void *arg. This function will be invoked in case of error and it will be given 3 arguments: the xlog handle, an integer that indicates the type of error and the arg specified in this call. Possible errors include:

XLOG_ENOMEM

lack of memory

XLOG_EOPEN

open(2) failed

XLOG_EFSTAT

fstat(2) failed

XLOG_ESIZE

hard limit exceeded

XLOG_SETFLAG

Argument list: int flag, int *value. The value of flag (one of those listed before) is set according to *value which should be either 0 or 1. The old flag value is placed in *value.

XLOG_GETFLAG

Argument list: int flag, int *value. The value of flag (one of those listed before) is placed in *value.

Xlogs of type XLOG_SYSLOG also support the following operations:

XLOG_FACILITY

Argument list: int facility. Sets the syslog facility to the specified value.

XLOG_LEVEL

Argument list: int level. Sets the default syslog level for this xlog to the specified value.

XLOG_PREEXEC

Argument list: void. Prepares the xlog for an impending exec operation

XLOG_POSTEXEC

Argument list: void. Informs the xlog that the exec failed

Xlogs of type XLOG_FILELOG also support the following operations:

XLOG_LIMITS

Argument list: unsigned soft_limit, unsigned hard_limit. Sets soft and hard limits on the size of the file. When the soft limit is exceeded a warning message is sent to the linked xlog (if there is no linked xlog, no message is sent) and when the hard limit is exceeded logging is terminated. The actual file size is checked every time this operation is applied to the file. If logging was terminated because the hard limit was exceeded and this operation increases the hard limit beyond the actual file size, logging will be resumed.

XLOG_SIZECHECK

Argument list: void. Checks the actual file size.

XLOG_GETFD

Argument list: int *value. Places in *value the file descriptor of the log file.

xlog_write() writes a message to the specified xlog. A NEWLINE is always appended to the message. The first occurrence of "%m" in buf is replaced by a string explaining the current value of errno. The flags argument is formed in the same way as in xlog_create(). One additional constant is available:

XLOG_SET_LEVEL

(XLOG_SYSLOG only) the next argument is an integer that should be used as the syslog level for this message instead of the default level of the xlog.

RETURN VALUES

xlog_parms() returns an error code (it returns XLOG_ENOERROR if it is successful).  

BUGS

Only the first occurrence of %m is replaced by an errno explanation.

Index

SYNOPSIS

DESCRIPTION

RETURN VALUES

BUGS