#include <apr.h>
#include <apr_file_io.h>
#include <apr_time.h>

Data Structures
struct	LOGMANAGER_OPTIONS
	Log manager configuration provided at creation time as an argument to new_logmanager(). More...
struct	LOGMANAGER
	The structure identifying a log manager. More...
Defines
#define	NOW (TIMESTAMP)0
	Use the system current time.
#define	LMGR_ACTIVE_LINK 0x01
	LOGMANAGER_OPTIONS flag - Maintain a link to the active log file.
#define	LMGR_BACKUP_LINKS 0x02
	LOGMANAGER_OPTIONS flag - Maintain links to backup logs.
#define	LMGR_HARD_LINKS 0x04
	LOGMANAGER_OPTIONS flag - Create hard links instead of symbolic links.
#define	LMGR_IGNORE_EOL 0x08
	LOGMANAGER_OPTIONS flag - Don't rotate on eol only.
#define	LMGR_IGNORE_ENOSPC 0x10
	LOGMANAGER_OPTIONS flag - ignore 'no more space' (ENOSPC) system errors.
#define	LMGR_PID_FILE 0x20
	LOGMANAGER_OPTIONS flag - Maintain a PID file as 'base_path'.pid.
#define	LOGMANAGER_API_VERSION 3
	The API version.
Typedefs
typedef apr_time_t	TIMESTAMP
	Timestamp (apr_time_t value or 'NOW').
Functions
LOGMANAGER *	new_logmanager (LOGMANAGER_OPTIONS *opts)
	Creates a log manager.
void	logmanager_destroy (LOGMANAGER *mp)
	Deletes a log manager.
void	logmanager_open (LOGMANAGER *mp, TIMESTAMP t)
	Opens a log manager.
void	logmanager_close (LOGMANAGER *mp)
	Closes a log manager.
void	logmanager_write (LOGMANAGER mp, const char buf, apr_off_t size, TIMESTAMP t)
	Sends data to a log manager.
void	logmanager_flush (LOGMANAGER *mp)
	Forces a flush to the log file.
void	logmanager_rotate (LOGMANAGER *mp, TIMESTAMP t)
	Triggers a rotation.
char *	logmanager_compression_list (void)
	Returns the list of supported compression schemes.
char *	logmanager_version (void)
	Returns the version of the library.
void	logmanager_display_stats (LOGMANAGER *mp)
	Displays internal stats.

Define Documentation

#define NOW (TIMESTAMP)0

Use the system current time.

When a function receives 'NOW' as timestamp argument, it converts it into the current system time.

Examples:: example.c.

#define LMGR_ACTIVE_LINK 0x01

LOGMANAGER_OPTIONS flag - Maintain a link to the active log file.

#define LMGR_BACKUP_LINKS 0x02

LOGMANAGER_OPTIONS flag - Maintain links to backup logs.

#define LMGR_HARD_LINKS 0x04

LOGMANAGER_OPTIONS flag - Create hard links instead of symbolic links.

#define LMGR_IGNORE_EOL 0x08

LOGMANAGER_OPTIONS flag - Don't rotate on eol only.

This flag inhibits the default buffering mechanism ensuring that rotations occur on end of lines only (no truncated last line in log files)

#define LMGR_IGNORE_ENOSPC 0x10

LOGMANAGER_OPTIONS flag - ignore 'no more space' (ENOSPC) system errors.

When this flag is set, the log manager ignores 'no more space/file system full' errors, silently discarding new data when no more space remains in the log file system.

Before setting this flag, you must be sure that you prefer discarding data than crashing the service. Can be used as a 'last chance' protection against DOS attacks.

Todo:: Should be able to send an alarm via an external system on ENOSPC ignored errors.

#define LMGR_PID_FILE 0x20

LOGMANAGER_OPTIONS flag - Maintain a PID file as 'base_path'.pid.

Examples:: example.c.

#define LOGMANAGER_API_VERSION 3

The API version.

Typedef Documentation

typedef apr_time_t TIMESTAMP

Timestamp (apr_time_t value or 'NOW').

The logmanager library functions receive their time information from the calling program, instead of getting it from the system clock. This way, the calling program controls the way time sent to a log manager varies, independantly from the 'real' (system) time. Different log managers can receive different timestamps as they are independant from each other.

This allows, for instance, to process some old data with the time information extracted from each data line.

Note:: Once a timestamp is provided in a function call, a subsequent call cannot provide a smaller timestamp value (no step back in time). If a timestamp value smaller than the previous one is provided, the previous one is used to ensure that the rotation/purge logic remains functional.

Function Documentation

LOGMANAGER* new_logmanager ( LOGMANAGER_OPTIONS * opts )

Creates a log manager.

This function creates a log manager object from a set of options. The options define its logic and the paths it will maintain.

Note:: This function does not write anything to the file system. It only allocates and initializes a LOGMANAGER struct in memory. Before sending data to the newly-created log manager, you must open it via a call to logmanager_open().

Parameters:

[in] opts A pointer to the log manager's options. This struct and the strings/pointers it may contain should be freed on return (every data needed by the log manager for internal use are transparently allocated/freed by the log manager).

Returns:: LOGMANAGER* A pointer to a newly allocated LOGMANAGER struct. This is the pointer to use in subsequent function calls.

Examples:: example.c.

void logmanager_destroy ( LOGMANAGER * mp )

Deletes a log manager.

Also frees the data allocated by new_logmanager()

Parameters:

[in] mp Pointer to a LOGMANAGER struct previously returned by new_logmanager().

Examples:: example.c.

void logmanager_open	(	LOGMANAGER *	mp,
		TIMESTAMP	t
	)

Opens a log manager.

Called after new_logmanager() before writing to a log manager

Parameters:

`[in]`	mp	Pointer to a LOGMANAGER struct previously returned by new_logmanager().
`[in]`	t	Timestamp (apr_time_t value or 'NOW')

Examples:: example.c.

void logmanager_close ( LOGMANAGER * mp )

Closes a log manager.

The log manager can then be reopened via logmanager_open() or destroyed via logmanager_destroy().

Parameters:

[in] mp Pointer to a LOGMANAGER struct previously returned by new_logmanager().

Examples:: example.c.

void logmanager_write	(	LOGMANAGER *	mp,
		const char *	buf,
		apr_off_t	size,
		TIMESTAMP	t
	)

Sends data to a log manager.

Parameters:

`[in]`	mp	Pointer to a LOGMANAGER struct previously returned by new_logmanager().
`[in]`	buf	The data to write.
`[in]`	size	The size in bytes of the data buffer to write
`[in]`	t	Timestamp (apr_time_t value or 'NOW')

Examples:: example.c.

void logmanager_flush ( LOGMANAGER * mp )

Forces a flush to the log file.

Flushes the remaining data to the file system. Mostly interesting to flush compressed streams so that they can be uncompressed by an external mechanism.

Note:: The log manager remains open.

Parameters:

[in] mp Pointer to a LOGMANAGER struct previously returned by new_logmanager().

void logmanager_rotate	(	LOGMANAGER *	mp,
		TIMESTAMP	t
	)

Triggers a rotation.

Triggers an immediate log rotation. Can also trigger a purge if the rotation causes the purge constraints to be exceeded.

Parameters:

`[in]`	mp	Pointer to a LOGMANAGER struct previously returned by new_logmanager().
`[in]`	t	Timestamp (apr_time_t value or 'NOW')

char* logmanager_compression_list ( void )

Returns the list of supported compression schemes.

Returns:: A dynamically allocated string containing the list of supported compression types, separated with ',' characters.

The caller has the responsibility to free the returned string.

char* logmanager_version ( void )

Returns the version of the library.

Returns:: the version of the managelogs package the library belongs to.

The caller has the responsibility to free the returned string.

void logmanager_display_stats ( LOGMANAGER * mp )

Displays internal stats.

Utility function displaying some internal stats and counters. Used for debugging and tests only.

Parameters:

[in] mp Pointer to a LOGMANAGER struct previously returned by new_logmanager().

logmanager.h File Reference

Data Structures

Defines

Typedefs

Functions

Define Documentation

Typedef Documentation

Function Documentation