XLOG(3X)

xlog_parms, xlog_create, xlog_destroy, xlog_write, xlog_control -- general purpose logging facility

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 ;

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

DESCRIPTION
The purpose of this library is to provide a general purpose logging facility by providing xlogs, logging objects that may be connected to various existent logging facilities. Currently, the only logging facilities supported are syslog(3) and logging to files. Log entries are timestamped lines which may contain arbitrary information.

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_ID
        precede each log entry with the xlog id

    XLOG_PRINT_PID
        precede each log entry with the process id (the process id will follow the xlog 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 while writing a log entry. 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 any of the limits is exceeded a message is sent to the linked xlog. (if there is no linked xlog, no message is sent) When the soft limit is exceeded a warning message is sent to the linked xlog (if the linked xlog is of the XLOG_SYSLOG type, the message will be sent at the LOG_ALERT level). If the exceeded limit is the hard limit, 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_create() returns an xlog handle or NULL if it fails.

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

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

SEE ALSO
openlog(3), syslog(3), closelog(3)

BUGS

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

There is no check for cycles when linking xlogs. In particular it is possible to link a xlog to itself.