Macros
#define	DS_LOG_CONFIG 0
	Used for log messages that indicate a problem or feedback with library configuration. More...

#define	DS_LOG_CRIT 2
	Used for log messages that indicate a serious failure. More...

#define	DS_LOG_DEBUG 7
	Used for tracing messages. More...

#define	DS_LOG_ERROR 3
	Used for log messages that indicate a problem. More...

#define	DS_LOG_FINER 8
	Used for fairly detailed tracing messages. More...

#define	DS_LOG_FINEST 9
	Used for the most finely detailed tracing messages. More...

#define	DS_LOG_INFO 6
	Used for informational messages. More...

#define	DS_LOG_MONITOR 128
	A modifier that will send the log message to the monitoring system in addition to the event log, even if the log level is below the monitoring threshold value. More...

#define	DS_LOG_NOTIFY 4
	Used for messages of greater importance than DS_LOG_WARN that may not indicate problems. More...

#define	DS_LOG_SYSLOG 512
	A modifier which will write the log message to the system log in addition to the event log regardless of the level passed to ds_log() or the level set by log-syslog-level. Using this modifier with ds_log() is equivalent to calling ds_syslog() without the modifier. More...

#define	DS_LOG_TERMINAL 256
	A modifier which will write the log message to the terminal in addition to the event log. More...

#define	DS_LOG_WARN 5
	Used for messages that indicate a potential problem. More...

Typedefs
typedef struct _ds_log	ds_log_t
	The log file object. More...

typedef void(*	ds_logcycled_t) (ds_log_t *log)
	Callback used when the log has cycled. More...

typedef void(*	ds_loglevelchange_t) (ds_log_t *log, int new_level)
	Callback used when the logging level of a log file is changed. More...

Functions
void	ds_cycle_all_logs (const char *suffix, long maxsize)
	Cycle all log files in the application. More...

int	ds_cycle_log (ds_log_t log, const char suffix, long maxsize)
	Cycle a specific log file. More...

int	ds_debug_level (const char *text)
	This function will convert a string into an appropriate debug level. More...

void	ds_free_log (ds_log_t *log)
	Destroy a log object. More...

void	ds_log (ds_log_t log, int level, const char fmt,...)
	Write a formatted string prefixed with log level and timestamp to the log object. More...

void	ds_log_category (ds_log_t log, int level, const char category_prefix, const char *fmt,...)
	Write a formatted string prefixed with category, log level and timestamp to the log object if the category configuration permits it. More...

void	ds_log_change_level_callback (ds_log_t *log, ds_loglevelchange_t change_cb)
	Set the level change callback for a given logfile. More...

ds_logcycled_t	ds_log_cycled_callback (ds_log_t *log, ds_logcycled_t cycle_cb)
	Set the cycle callback for a given logfile. More...

int	ds_log_flush (ds_log_t *log)
	flush log buffers to disk More...

int	ds_log_get_level (ds_log_t *log)
	Get the current loglevel for the given logfile. More...

char *	ds_log_getfilename (ds_log_t *log)
	Get the filename of a log object. More...

char *	ds_log_getname (ds_log_t *log)
	Get the name of a log object. More...

int	ds_log_set_log_level (ds_log_t log, const char level)
	Set the log level for a particular logfile. More...

ds_log_t *	ds_new_headed_log (const char name, const char logname, const char *header)
	Create a new log object with a header. More...

ds_log_t *	ds_new_level_log (const char name, const char logname, ds_loglevelchange_t change_cb)
	Create a new log object. More...

ds_log_t *	ds_new_log (const char name, const char logname)
	Create a new log object. More...

void	ds_printf (ds_log_t log, const char fmt,...)
	Write a formatted string to a log object. More...

void	ds_printf_time (ds_log_t log, const char fmt,...)
	Write a formatted string prefixed with a timestamp string to a log object. More...

void	ds_printf_time_ap (ds_log_t log, const char extra, const char *fmt, va_list ap)
	Write a formatted string prefixed with a timestamp string to a log object. More...

void	ds_syslog (ds_log_t log, int level, const char fmt,...)
	Write a formatted string to a log object and to the system log. More...

void	ds_write (ds_log_t log, void data, size_t len)
	Write binary data to a log object. More...

void	ds_writev (ds_log_t log, struct iovec vector, int count)
	Write binary data to a log object. More...

Detailed Description

DataSource's log files keep a record of all data and to what destinations the data was sent.

The DataSource SDK logging API permits you to create your own logging functions

Log file names can use the following abbreviations:

%r can be used to represent the configured application-root.
%d can be used to represent the configured log-dir.
%a can be used to represent the configured application-name.
%n can be used to represent the configured application-name.
%M can be used to represent the major version of the DataSource Libraries.
%m can be used to represent the minor version of the DataSource Libraries.
%h can be used to represent the hostname.
%u can be used to represent the home directory of the user running the application.

Macro Definition Documentation

#define DS_LOG_CONFIG 0

Used for log messages that indicate a problem or feedback with library configuration.

#define DS_LOG_CRIT 2

Used for log messages that indicate a serious failure.

#define DS_LOG_DEBUG 7

Used for tracing messages.

#define DS_LOG_ERROR 3

Used for log messages that indicate a problem.

#define DS_LOG_FINER 8

Used for fairly detailed tracing messages.

#define DS_LOG_FINEST 9

Used for the most finely detailed tracing messages.

#define DS_LOG_INFO 6

Used for informational messages.

#define DS_LOG_MONITOR 128

A modifier that will send the log message to the monitoring system in addition to the event log, even if the log level is below the monitoring threshold value.

#define DS_LOG_NOTIFY 4

Used for messages of greater importance than DS_LOG_WARN that may not indicate problems.

#define DS_LOG_SYSLOG 512

A modifier which will write the log message to the system log in addition to the event log regardless of the level passed to ds_log() or the level set by log-syslog-level. Using this modifier with ds_log() is equivalent to calling ds_syslog() without the modifier.

#define DS_LOG_TERMINAL 256

A modifier which will write the log message to the terminal in addition to the event log.

#define DS_LOG_WARN 5

Used for messages that indicate a potential problem.

Typedef Documentation

typedef struct _ds_log ds_log_t

The log file object.

typedef void(* ds_logcycled_t) (ds_log_t *log)

Callback used when the log has cycled.

Parameters

log	The logfile that has cycled

typedef void(* ds_loglevelchange_t) (ds_log_t *log, int new_level)

Callback used when the logging level of a log file is changed.

Parameters

log	The logfile the change has happend to
new_level	The new debug level

Function Documentation

void ds_cycle_all_logs	(	const char *	suffix,
		long	maxsize
	)

Cycle all log files in the application.

Parameters

suffix	Suffix to use for the filename of the old log
maxsize	Size (in bytes) at which logs are cycled

Note: Log cycling can be configured and this function is only of use if customised cycling is required

If maxsize is -1 the configured default is used. If maxsize is 0 then the log isn't cycled based on size.

int ds_cycle_log	(	ds_log_t *	log,
		const char *	suffix,
		long	maxsize
	)

Cycle a specific log file.

Parameters

log	The Log object
suffix	Suffix to use for the filename of the old log
maxsize	Size (in bytes) at which logs are cycled

Return values

0	- Log file was cycled
-1	- Log file was not cycled

If maxsize is -1 the configured default is used. If maxsize is 0 then the log isn't cycled based on size.

int ds_debug_level ( const char * text )

This function will convert a string into an appropriate debug level.

Parameters

text	The string to convert

Returns: An appropriate debug level or -1 if not recognised

Example:

ds_debug_level("INFO);

Will return the value DS_LOG_INFO

void ds_free_log ( ds_log_t * log )

Destroy a log object.

Parameters

log	The log object to destroy

void ds_log	(	ds_log_t *	log,
		int	level,
		const char *	fmt,
			...
	)

Write a formatted string prefixed with log level and timestamp to the log object.

Parameters

log	The log object
level	The level that this message should be logged at (for example DS_LOG_INFO).
fmt	The format string

Note: The log object should be of the type that is returned by ds_new_level_log.

This function uses standard print style formatting options.

void ds_log_category	(	ds_log_t *	log,
		int	level,
		const char *	category_prefix,
		const char *	fmt,
			...
	)

Write a formatted string prefixed with category, log level and timestamp to the log object if the category configuration permits it.

Parameters

log	The log object
level	The level that this message should be logged at (for example DS_LOG_INFO).
category_prefix	A string that identifies the log category
fmt	The format string

Note: The log object should be of the type that is returned by ds_new_level_log.

This function uses standard print style formatting options.

void ds_log_change_level_callback	(	ds_log_t *	log,
		ds_loglevelchange_t	change_cb
	)

Set the level change callback for a given logfile.

Parameters

log	The log file
change_cb	The callback to call when the debug level changes

ds_logcycled_t ds_log_cycled_callback	(	ds_log_t *	log,
		ds_logcycled_t	cycle_cb
	)

Set the cycle callback for a given logfile.

Parameters

log	The log file
cycle_cb	The callback to call when the log cycles

Return values

Any	existing callback

int ds_log_flush ( ds_log_t * log )

flush log buffers to disk

Parameters

log	- The log to be flushed

Return values

0	- Log was flushed successfully
-1	- An error occurred flushing the logs

int ds_log_get_level ( ds_log_t * log )

Get the current loglevel for the given logfile.

Parameters

log	The logfile

Return values

The log level

char* ds_log_getfilename ( ds_log_t * log )

Get the filename of a log object.

Parameters

log	The Log object

Returns: The filename of this log object

char* ds_log_getname ( ds_log_t * log )

Get the name of a log object.

Parameters

log	- The log object

Returns: The name of the logfile (eg event_log)

int ds_log_set_log_level	(	ds_log_t *	log,
		const char *	level
	)

Set the log level for a particular logfile.

Parameters

log	The log to set the level for
level	A textual string representing the log level

Return values

0	- Log level was set
-1	- Log level wasn't set (invalid level supplied or inappropriate log file)

ds_log_t* ds_new_headed_log	(	const char *	name,
		const char *	logname,
		const char *	header
	)

Create a new log object with a header.

Parameters

name	Name of the log object
logname	File name
header	The header text

Returns: A new log object

The header will be added to the beginning of the log file every time it cycles. The header text can be a maximum of 80 characters

The filename given should be either absolute or relative to the configured log directory (log-dir)

Any log can be configured to cycle individually (add-log-cycle)

ds_log_t* ds_new_level_log	(	const char *	name,
		const char *	logname,
		ds_loglevelchange_t	change_cb
	)

Create a new log object.

Parameters

name	Name of the log object
logname	File name
change_cb	Callback for change log levels

Returns: A new log object

The filename given should be either absolute or relative to the configured log directory (log-dir)

Any log can be configured to cycle individually (add-log-cycle)

ds_log_t* ds_new_log	(	const char *	name,
		const char *	logname
	)

Create a new log object.

Parameters

name	Name of the log object
logname	File name

Returns: A new log object

The filename given should be either absolute or relative to the configured log directory (log-dir)

Any log can be configured to cycle individually (add-log-cycle)

void ds_printf	(	ds_log_t *	log,
		const char *	fmt,
			...
	)

Write a formatted string to a log object.

Parameters

log	The log object
fmt	The format string

This function uses standard printf style formatting options.

void ds_printf_time	(	ds_log_t *	log,
		const char *	fmt,
			...
	)

Write a formatted string prefixed with a timestamp string to a log object.

Parameters

log	The log object
fmt	The format string

This function uses standard printf style formatting options.

The time stamp produced by this function is of the form:

Nov 18 10:37:47.321 +0000:

void ds_printf_time_ap	(	ds_log_t *	log,
		const char *	extra,
		const char *	fmt,
		va_list	ap
	)

Write a formatted string prefixed with a timestamp string to a log object.

Parameters

log	The log object
extra	An additional string
fmt	The format string
ap	An argument list

The parameter extra is inserted after the timestamp and before the formatted string in the output stream

This function uses standard printf style formatting options.

void ds_syslog	(	ds_log_t *	log,
		int	level,
		const char *	fmt,
			...
	)

Write a formatted string to a log object and to the system log.

Parameters

log	The log object
level	The level that this message should be logged at (for example DS_LOG_INFO).
fmt	The format string

Note: The format string should not end with a newline character; The log is written to syslog regardless of the level set by log-syslog-level or the level passed in the call to ds_syslog().

See also: DS_LOG_SYSLOG

void ds_write	(	ds_log_t *	log,
		void *	data,
		size_t	len
	)

Write binary data to a log object.

Parameters

log	The log object
data	Pointer to the start of data to write
len	Size of data to write (in bytes)

void ds_writev	(	ds_log_t *	log,
		struct iovec *	vector,
		int	count
	)

Write binary data to a log object.

Parameters

log	The log object
vector	writev vector
count	writev count

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation