Log-Object

Interface to access log service.  An interface is a structure which lists function pointers.  These function pointers point to functions exported by a service implementation.  Used in LogWriter and LogMain.

Summary
Log-ObjectInterface to access log service.
CopyrightThis program is free software.
Files
C-kern/api/io/writer/log/log.hHeader file of Log-Object.
Types
struct log_tExport log_t.
struct log_itExport interface log_it.
struct log_header_tExport log_header_t.
log_text_fDeclare function pointer which writes a text resource into logbuffer_t.
Enumerations
log_config_eUsed to configure system wide restrictions.
log_flags_eUsed to configure system wide restrictions.
log_channel_eUsed to switch between log channels.
log_state_eUsed to configure the state of a log_channel_e.
log_tUses iobj_DECLARE to declare object supporting interface log_it.
generic
genericcast_logCasts parameter iobj to pointer to log_t.
log_itThe function table which describes the log service.
printfWrites a new log entry to in internal buffer.
printtextWrites text resource as new log entry to in internal buffer.
flushbufferWrites content of buffer to configured file descriptor and clears log buffer.
clearbufferClears log buffer (sets length of logbuffer to 0).
getbufferReturns content of log buffer as C-string and its size in bytes.
getstateReturns configured log_state_e for a specific log_channel_e channel.
comapreReturns 0 if logbuffer compares equal to content in log for a specific log_channel_e channel.
setstateSets log_state_e logstate for a specific log_channel_e channel.
generic
genericcast_logitCasts pointer logif into pointer to interface log_it.
log_it_DECLAREDeclares a function table for accessing a log service.
log_header_tContains information for a log header.
lifetime
inline implementation
log_t
genericcast_logImplements log_t.genericcast_log.
log_it
genericcast_logitImplements log_it.genericcast_logit.
log_it_DECLAREImplements log_it.log_it_DECLARE.

Copyright

This program is free software.  You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

Author

© 2011 Jörg Seebohn

Files

C-kern/api/io/writer/log/log.h

Header file of Log-Object.

Types

struct log_t

typedef struct log_t log_t

Export log_t.  Interfaceable log object.

struct log_it

typedef struct log_it log_it

Export interface log_it.  See log_it_DECLARE for a description of the functional interface.

struct log_header_t

typedef struct log_header_t log_header_t

Export log_header_t.

log_text_f

typedef void (*log_text_f)(struct logbuffer_t * logbuffer, va_list vargs)

Declare function pointer which writes a text resource into logbuffer_t.

Enumerations

log_config_e

Used to configure system wide restrictions.

log_config_MINSIZEThe minimum size in bytes of one log entry before it is possibly truncated.  If the buffer is bigger it is not truncated.

log_flags_e

Used to configure system wide restrictions.

log_flags_NONEIndicates that the log entry does not change append or not append state.  If the last call to print contained log_flags_START the new entry is appended.  If the last call to print contained log_flags_END the new entry is not appended.
log_flags_STARTIndicates that this is the beginning of a new log entry.  This flag implicitly ends the previous log entry if not done explicitly.  The log entry is therefore not appended to a previous one.  Every following log output is now appended to a memory buffer and truncated if necessary until another call to print is done with flag set to log_flags_END or log_flags_START.
log_flags_ENDIndicates that this is the last part of a log entry.  You can set log_flags_START and log_flags_END at the same time to indicate that the printed log entry should not be appended to a previous one and the following entries should not be appended to this one.
log_flags_OPTIONALHEADERA given log_header_t is only written before the log entry if the pointer to the function name in log_header_t differs from the pointer given in the previous call.  The flag log_flags_END sets the remembered pointer to the function name to 0.  Set this flag on the last part of the log entry if another header could be written in the same function with flag log_flags_START.  Both log macros TRACEABORT_ERRLOG and TRACEABORTFREE_ERRLOG set this flag.  They do not know if another call to TRACESYSCALL_ERRLOG already printed a header.

log_channel_e

Used to switch between log channels.

log_channel_USERERRUses STDERR channel for log output.  This channel is used for user error messages.  The logged content is written immediately to STDERR without buffering.  In case of a daemon process the channel should be redirected to log_channel_ERR and/or an additional entry into log_channel_ERR should be written.
log_channel_TESTUses test channel for log output.  The test channel is used for additional TEST output in the running production system.  This channel is written to STDERR if not configured otherwise.
log_channel_WARNUses warning channel for log output.  The warning channel is used to warn of non critical conditions.  This channel is written to STDERR if not configured otherwise.
log_channel_ERRUses error channel for log output.  The error channel is used to log system error which should not occur and which are not critical to the running process.  This channel is written to STDERR if not configured otherwise.
log_channel_NROFCHANNELUse this value to determine the number of different channels numbered from 0 up to (log_channel_NROFCHANNEL-1).

log_state_e

Used to configure the state of a log_channel_e.

log_state_IGNOREDIgnore any writing to this channel.
log_state_BUFFEREDNormal operation mode.  All log entries are buffered until the buffer is full and then the buffer is written all at once.
log_state_UNBUFFEREDEvery log entry is constructed in a buffer and if the last part of the entry is added to it the log entry is written out as a whole.
log_state_IMMEDIATEEvery part of a log entry is written immediately without waiting for the last part end.
log_state_NROFSTATEUse this value to determine the number of different states numbered from 0 up to (log_state_NROFSTATE-1).

log_t

iobj_DECLARE(log_t,
log)

Uses iobj_DECLARE to declare object supporting interface log_it.

Summary
generic
genericcast_logCasts parameter iobj to pointer to log_t.

generic

genericcast_log

log_t * genericcast_log(void *iobj)

Casts parameter iobj to pointer to log_t. iobj must be a pointer to an anonymous interfaceable log object.

log_it

struct log_it

The function table which describes the log service.

Summary
printfWrites a new log entry to in internal buffer.
printtextWrites text resource as new log entry to in internal buffer.
flushbufferWrites content of buffer to configured file descriptor and clears log buffer.
clearbufferClears log buffer (sets length of logbuffer to 0).
getbufferReturns content of log buffer as C-string and its size in bytes.
getstateReturns configured log_state_e for a specific log_channel_e channel.
comapreReturns 0 if logbuffer compares equal to content in log for a specific log_channel_e channel.
setstateSets log_state_e logstate for a specific log_channel_e channel.
generic
genericcast_logitCasts pointer logif into pointer to interface log_it.
log_it_DECLAREDeclares a function table for accessing a log service.

printf

void (
   *printf
) (void * log, uint8_t channel, uint8_t flags, const log_header_t * header, const char * format, ... ) __attribute__ ((__format__ (__printf__, 5, 6)))

Writes a new log entry to in internal buffer.  Parameter channel must be set to a value from log_channel_e.  If header is not 0 a header is written which contains “[thread id, timestamp]\nfuncname() file:linenr\n, Error NR - DESCRIPTION\n”.  If the entry is bigger than log_config_MINSIZE it may be truncated if internal buffer size is lower.  See logwriter_t.printf_logwriter for an implementation.

printtext

void (
   *printtext
) (void * log, uint8_t channel, uint8_t flags, const log_header_t * header, log_text_f textf, ... )

Writes text resource as new log entry to in internal buffer.  See printf for a description of the parameter.  The variable parameter list must match the resource.

flushbuffer

void (*flushbuffer) (void * log, uint8_t channel)

Writes content of buffer to configured file descriptor and clears log buffer.  This call is ignored if buffer is empty or log is not configured to be in buffered mode.  See logwriter_t.flushbuffer_logwriter for an implementation.

clearbuffer

void (*clearbuffer) (void * log, uint8_t channel)

Clears log buffer (sets length of logbuffer to 0).  This call is ignored if the log is not configured to be in buffered mode.  See logwriter_t.clearbuffer_logwriter for an implementation.

getbuffer

void (
   *getbuffer
) (const void * log, uint8_t channel, /*out*/uint8_t ** buffer, /*out*/size_t * size)

Returns content of log buffer as C-string and its size in bytes.  The returned values are valid as long as no other function is called on log.  The string has a trailing NULL byte, i.e. buffer[size] == 0.  See logwriter_t.getbuffer_logwriter for an implementation.

getstate

uint8_t (*getstate) (const void * log, uint8_t channel)

Returns configured log_state_e for a specific log_channel_e channel.  You can switch log_state_e by calling setstate.

comapre

Returns 0 if logbuffer compares equal to content in log for a specific log_channel_e channel.  The return value EINVAL indicates not equal.  The comparison should ignore timestamps.

setstate

void (*setstate) (void * log, uint8_t channel, uint8_t logstate)

Sets log_state_e logstate for a specific log_channel_e channel.  You can query the current log_state_e by calling getstate.

generic

genericcast_logit

log_it * genericcast_logit(void *logif,
TYPENAME log_t)

Casts pointer logif into pointer to interface log_it.  Parameter logif must point to a type declared with log_it_DECLARE.  The other parameters must be the same as in log_it_DECLARE without the first.

log_it_DECLARE

void log_it_DECLARE(TYPENAME declared_it,
TYPENAME log_t)

Declares a function table for accessing a log service.  The declared interface is structural compatible with log_it.  The difference between the newly declared interface and the generic interface is the type of the first parameter.

See log_it for a list of declared functions.

Parameter

declared_itThe name of the structure which is declared as the interface.  The name should have the suffix “_it”.
log_tThe type of the log object which is the first parameter of all interface functions.

log_header_t

struct log_header_t

Contains information for a log header.  It describes the function name, file name and line number of the log statement.

Summary
lifetime

lifetime

inline implementation

Summary
log_t
genericcast_logImplements log_t.genericcast_log.
log_it
genericcast_logitImplements log_it.genericcast_logit.
log_it_DECLAREImplements log_it.log_it_DECLARE.

log_t

genericcast_log

#define genericcast_log(iobj) genericcast_iobj(iobj, log)

Implements log_t.genericcast_log.

log_it

genericcast_logit

#define genericcast_logit(
   logif,
   log_t
) ( __extension__ ({ static_assert( &((typeof(logif))0)->printf == (void(**)(log_t*,uint8_t,uint8_t, const log_header_t*, const char*,...)) &((log_it*)0)->printf && &((typeof(logif))0)->printtext == (void(**)(log_t*,uint8_t,uint8_t, const log_header_t*, log_text_f,...)) &((log_it*)0)->printtext && &((typeof(logif))0)->flushbuffer == (void(**)(log_t*,uint8_t)) &((log_it*)0)->flushbuffer && &((typeof(logif))0)->clearbuffer == (void(**)(log_t*,uint8_t)) &((log_it*)0)->clearbuffer && &((typeof(logif))0)->getbuffer == (void(**)(const log_t*,uint8_t, uint8_t**,size_t*)) &((log_it*)0)->getbuffer && &((typeof(logif))0)->getstate == (uint8_t(**)(const log_t*, uint8_t)) &((log_it*)0)->getstate && &((typeof(logif))0)->compare == (int(**)(const log_t*, uint8_t, size_t,const uint8_t*)) &((log_it*)0)->compare && &((typeof(logif))0)->setstate == (void(**)(log_t*,uint8_t, uint8_t)) &((log_it*)0)->setstate, "ensure same structure"); (log_it*) (logif); }))

Implements log_it.genericcast_logit.

log_it_DECLARE

Implements log_it.log_it_DECLARE.

Interface to access log service.
typedef struct log_t log_t
Export log_t.
iobj_DECLARE(log_t,
log)
Uses iobj_DECLARE to declare object supporting interface log_it.
typedef struct log_it log_it
Export interface log_it.
struct log_it
The function table which describes the log service.
typedef struct log_header_t log_header_t
Export log_header_t.
struct log_header_t
Contains information for a log header.
typedef void (*log_text_f)(struct logbuffer_t * logbuffer, va_list vargs)
Declare function pointer which writes a text resource into logbuffer_t.
Used to switch between log channels.
#define iobj_DECLARE(
   declared_t,
   typenameprefix
) struct declared_t { struct typenameprefix##_t * object ; struct typenameprefix##_it * iimpl ; }
Implements iobj_t.iobj_DECLARE.
log_t * genericcast_log(void *iobj)
Casts parameter iobj to pointer to log_t.
void (
   *printf
) (void * log, uint8_t channel, uint8_t flags, const log_header_t * header, const char * format, ... ) __attribute__ ((__format__ (__printf__, 5, 6)))
Writes a new log entry to in internal buffer.
void (
   *printtext
) (void * log, uint8_t channel, uint8_t flags, const log_header_t * header, log_text_f textf, ... )
Writes text resource as new log entry to in internal buffer.
void (*flushbuffer) (void * log, uint8_t channel)
Writes content of buffer to configured file descriptor and clears log buffer.
void (*clearbuffer) (void * log, uint8_t channel)
Clears log buffer (sets length of logbuffer to 0).
void (
   *getbuffer
) (const void * log, uint8_t channel, /*out*/uint8_t ** buffer, /*out*/size_t * size)
Returns content of log buffer as C-string and its size in bytes.
uint8_t (*getstate) (const void * log, uint8_t channel)
Returns configured log_state_e for a specific log_channel_e channel.
Used to configure the state of a log_channel_e.
void (*setstate) (void * log, uint8_t channel, uint8_t logstate)
Sets log_state_e logstate for a specific log_channel_e channel.
log_it * genericcast_logit(void *logif,
TYPENAME log_t)
Casts pointer logif into pointer to interface log_it.
void log_it_DECLARE(TYPENAME declared_it,
TYPENAME log_t)
Declares a function table for accessing a log service.
#define genericcast_log(iobj) genericcast_iobj(iobj, log)
Implements log_t.genericcast_log.
#define genericcast_logit(
   logif,
   log_t
) ( __extension__ ({ static_assert( &((typeof(logif))0)->printf == (void(**)(log_t*,uint8_t,uint8_t, const log_header_t*, const char*,...)) &((log_it*)0)->printf && &((typeof(logif))0)->printtext == (void(**)(log_t*,uint8_t,uint8_t, const log_header_t*, log_text_f,...)) &((log_it*)0)->printtext && &((typeof(logif))0)->flushbuffer == (void(**)(log_t*,uint8_t)) &((log_it*)0)->flushbuffer && &((typeof(logif))0)->clearbuffer == (void(**)(log_t*,uint8_t)) &((log_it*)0)->clearbuffer && &((typeof(logif))0)->getbuffer == (void(**)(const log_t*,uint8_t, uint8_t**,size_t*)) &((log_it*)0)->getbuffer && &((typeof(logif))0)->getstate == (uint8_t(**)(const log_t*, uint8_t)) &((log_it*)0)->getstate && &((typeof(logif))0)->compare == (int(**)(const log_t*, uint8_t, size_t,const uint8_t*)) &((log_it*)0)->compare && &((typeof(logif))0)->setstate == (void(**)(log_t*,uint8_t, uint8_t)) &((log_it*)0)->setstate, "ensure same structure"); (log_it*) (logif); }))
Implements log_it.genericcast_logit.
Write error messages to STDERR for diagnostic purposes.
Used in static initializer for threadcontext_t.
Implements log_it.log_it_DECLARE.
Indicates that this is the beginning of a new log entry.
Indicates that this is the last part of a log entry.
#define TRACEABORT_ERRLOG(
   err
) TRACE_NOARG_ERRLOG(log_flags_END|log_flags_OPTIONALHEADER, FUNCTION_ABORT, err)
Logs the abortion of a function and the its corresponding error code.
#define TRACEABORTFREE_ERRLOG(
   err
) TRACE_NOARG_ERRLOG(log_flags_END|log_flags_OPTIONALHEADER, FUNCTION_ABORT_FREE, err)
Logs that an error occurred during free_XXX or delete_XXX.
#define TRACESYSCALL_ERRLOG(
   sys_fctname,
   err
) TRACE_ERRLOG(log_flags_START, FUNCTION_SYSCALL, err, sys_fctname)
Logs reason of failure and name of called system function.
The minimum size in bytes of one log entry before it is possibly truncated.
void printf_logwriter(
   logwriter_t *lgwrt,
   uint8_t channel,
   uint8_t flags,
   const struct log_header_t *header,
   const char *format,
    ...
) __attribute__ ((__format__ (__printf__, 5, 6)))
Writes new log entry to internal buffer.
void flushbuffer_logwriter(logwriter_t *lgwrt,
uint8_t channel)
Writes content of buffer to STDERR or configured file descriptor and clears log buffer.
void clearbuffer_logwriter(logwriter_t *lgwrt,
uint8_t channel)
Clears log buffer (sets length of logbuffer to 0).
void getbuffer_logwriter(const logwriter_t *lgwrt,
uint8_t channel,
/*out*/uint8_t **buffer,
/*out*/size_t *size)
Returns content of internal buffer corrseponding to channel as C-string.
Close