log.c File Reference

The log object. More...

#include "config.h"
#include <fcntl.h>
#include <stdarg.h>
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <time.h>
#include <glib.h>
#include "file.h"
#include "item.h"
#include "event.h"
#include "callback.h"
#include "debug.h"
#include "xmlconfig.h"
#include "log.h"
#include <errno.h>

Data Structures
struct	log_data
struct	log

Functions
static void	strftime_localtime (char *buffer, int size, char *fmt)
	Stores formatted time to a string.
static void	expand_filenames (struct log *this_)
	Expands placeholders in a filename.
static void	log_set_last_flush (struct log *this_)
	Sets the time at which the log buffer was last flushed.
static void	log_open (struct log *this_)
	Opens a log file.
static void	log_close (struct log *this_)
	Closes a log file.
static void	log_flush (struct log *this_, enum log_flags flags)
	Flushes the buffer of a log.
static int	log_flush_required (struct log *this_)
	Determines if the maximum buffer size of a log has been exceeded.
static void	log_change (struct log *this_)
	Rotates a log file.
static int	log_change_required (struct log *this_)
	Determines if the log must be rotated.
static void	log_timer (struct log *this_)
	Determines if the flush interval of a log has elapsed and flushes the buffer if needed.
int	log_get_attr (struct log *this_, enum attr_type type, struct attr *attr, struct attr_iter *iter)
	Gets an attribute.
struct log *	log_new (struct attr *parent, struct attr **attrs)
	Creates and initializes a new log object.
void	log_set_header (struct log *this_, char *data, int len)
	Sets the header for a log file.
void	log_set_trailer (struct log *this_, char *data, int len)
	Sets the trailer for a log file.
void	log_write (struct log *this_, char *data, int len, enum log_flags flags)
	Writes to a log.
void *	log_get_buffer (struct log *this_, int *len)
	Returns the data buffer of a log object and its length.
void	log_printf (struct log *this_, char *fmt,...)
	Writes a formatted string to a log.
void	log_destroy (struct log *this_)
	Destroys a log object and frees up its memory.

Variables
struct object_func	log_func

Detailed Description

The log object.

This file implements everything needed for logging: the log object and its functions.

Author

Navit Team

Date

2005-2014

Function Documentation

expand_filenames()

static void expand_filenames ( struct log *  this_ )

static

Expands placeholders in a filename.

This function examines the log->filename and replaces any placeholders found in it with date, time or an incremental number. If an incremental number is specified, the function will ensure the filename is unique. The expanded filename will be stored log->filename_ex2. The function uses log->filename_ex1 to store the partly-expanded filename.

Parameters

this_

The log object.

References file_exists(), log::filename, log::filename_ex1, log::filename_ex2, and strftime_localtime().

Referenced by log_change(), and log_new().

log_change()

static void log_change ( struct log *  this_ )

static

Rotates a log file.

This function rotates a log by stopping and immediately restarting it. Stopping flushes the buffer and closes the file; restarting determines the new file name and opens the file as needed (depending on the lazy member).

Depending on the file name format and how the function was called, a new log file will be created or the old log file will be reused (appended to or overwritten, depending on log->overwrite): if the file name includes an incremental number, the new file will always have a different name. If a previous call to log_change_required() returned true, the new file will also have a different name. In all other cases the new file will have the same name as the old one, causing the old file to be overwritten or appended to.

Parameters

this_

The log object.

References expand_filenames(), log::lazy, log_close(), log_flush(), and log_open().

Referenced by log_write().

log_change_required()

static int log_change_required ( struct log *  this_ )

static

Determines if the log must be rotated.

This function expands the date and time placeholders in log->filename to determine if the resulting part of the filename has changed.

Parameters

this_

The log object.

Returns

True if the date/time-dependent part of the filename has changed, false otherwise.

References log::filename, log::filename_ex1, and strftime_localtime().

Referenced by log_write().

log_close()

static void log_close ( struct log *  this_ )

static

Closes a log file.

This function writes the trailer to a log file, flushes it and closes the log file for log.

Parameters

this_

The log object.

References log_data::data, log::f, log_data::len, and log::trailer.

Referenced by log_change(), and log_destroy().

log_destroy()

void log_destroy

(

struct log *

this_

)

Destroys a log object and frees up its memory.

Parameters

this_

The log object.

References attr_list_free(), callback_destroy(), dbg, event_remove_timeout(), log_close(), log_flush(), lvl_debug, log::timer, and log::timer_callback.

log_flush()

static void log_flush ( struct log *  this_, enum log_flags  flags  )

static

Flushes the buffer of a log.

This function writes buffered log data to the log file associated with log and updates log->last_flush with the current time.

If log->lazy is true, this function will open the file if needed, else the file must be opened with log_open() prior to calling this function.

If the file is empty, the header will be written first, followed by the buffer data. log->empty will be set to zero if header or data are written to the file.

Parameters

this_

The log object.

flags

Flags to control behavior of the function: log_flag_replace_buffer: ignored log_flag_force_flush: ignored log_flag_keep_pointer: keeps the file pointer at the start position of the new data log_flag_keep_buffer: prevents clearing of the buffer after a successful write (default is to clear the buffer). log_flag_truncate: truncates the log file at the current position. On the Win32 Base API, this flag has no effect.

References log_data::data, log::data, dbg, log::empty, log::f, log::header, log::lazy, log_data::len, log_flag_keep_buffer, log_flag_keep_pointer, log_flag_truncate, log_open(), log_set_last_flush(), lvl_error, log_data::max_len, and log::trailer.

Referenced by log_change(), log_destroy(), log_timer(), and log_write().

log_flush_required()

static int log_flush_required ( struct log *  this_ )

static

Determines if the maximum buffer size of a log has been exceeded.

This function examines the size of the data buffer to determine if it exceeds the maximum size specified in log->flush_size and thus needs to be flushed.

Parameters

this_

The log object.

Returns

True if the cache needs to be flushed, false otherwise.

References log::data, log::flush_size, and log_data::len.

Referenced by log_write().

log_get_attr()

int log_get_attr	(	struct log *	this_,
		enum attr_type	type,
		struct attr *	attr,
		struct attr_iter *	iter
	)

Gets an attribute.

Parameters

this_	The log object.
attr_type	The attribute type to return
attr	Points to a struct attr to store the attribute
iter	An attribute iterator

Returns

True for success, false for failure

References attr_generic_get_attr(), and type.

Referenced by navit_add_log(), vehicle_add_log(), and vehicle_log_gpx().

log_get_buffer()

void * log_get_buffer	(	struct log *	this_,
		int *	len
	)

Returns the data buffer of a log object and its length.

Parameters

this_	The log object.
len	Points to an int which will receive the length of the buffer. This can be NULL, in which case no information on buffer length will be stored.

Returns

Pointer to the data buffer.

References log_data::data, log::data, and log_data::len.

Referenced by vehicle_log_binfile().

log_new()

struct log * log_new	(	struct attr *	parent,
		struct attr **	attrs
	)

Creates and initializes a new log object.

Parameters

parent	The parent object.
attrs	Points to an array of pointers to attributes for the new log object

Returns

The new log object, or NULL if creation fails.

References attr_list_dup(), attr_search(), callback_cast, callback_new_1, data, dbg, event_add_timeout(), expand_filenames(), file_wordexp_destroy(), file_wordexp_get_array(), file_wordexp_get_count(), file_wordexp_new(), log::filename, filename, log::flush_size, log::flush_time, log::lazy, log_func, log_open(), log_set_last_flush(), log_timer(), lvl_debug, log::mkdir, navit_object_ref(), attr::num, log::overwrite, log::timer, log::timer_callback, and attr::u.

log_open()

static void log_open ( struct log *  this_ )

static

Opens a log file.

This function opens the log file for log. The file name must be specified by log->filename_ex2 before this function is called.

log->overwrite specifies the behavior if the file exists: if true, an existing file will be overwritten, else it will be appended to.

If the directory specified in the filename does not exist and the log->mkdir is true, it will be created.

After the function returns, log->f will contain the file handle (or NULL, if the operation failed) and log->empty will indicate if the file is empty. log->last_flush will be updated with the current time.

Parameters

this_

The log object.

References log::empty, log::f, file_mkdir(), log::filename_ex2, log_set_last_flush(), log::mkdir, and log::overwrite.

Referenced by log_change(), log_flush(), and log_new().

log_printf()

void log_printf	(	struct log *	this_,
		char *	fmt,
			...
	)

Writes a formatted string to a log.

This function formats a string in a fashion similar to printf() and related functions and writes it to a log using log_write().

Parameters

this_	The log object.
fmt	The format string.
...	Additional arguments must be specified for each placeholder in the format string.

References LOG_BUFFER_SIZE, log_write(), and size.

log_set_header()

void log_set_header	(	struct log *	this_,
		char *	data,
		int	len
	)

Sets the header for a log file.

This function sets the header, which is to be inserted into any log file before the actual log data.

Parameters

this_	The log object.
data	The header data.
len	Size of the header data to be copied, in bytes.

References log_data::data, data, log::header, log_data::len, and log_data::max_len.

Referenced by navit_add_log(), and vehicle_add_log().

log_set_last_flush()

static void log_set_last_flush ( struct log *  this_ )

static

Sets the time at which the log buffer was last flushed.

This function sets log->last_flush to current time.

Parameters

this_

The log object.

Referenced by log_flush(), log_new(), and log_open().

log_set_trailer()

void log_set_trailer	(	struct log *	this_,
		char *	data,
		int	len
	)

Sets the trailer for a log file.

This function sets the trailer, which is to be added to any log file after the actual log data.

Parameters

this_	The log object.
data	The trailer data.
len	Size of the trailer data to be copied, in bytes.

References log_data::data, data, log_data::len, log_data::max_len, and log::trailer.

Referenced by vehicle_add_log().

log_timer()

static void log_timer ( struct log *  this_ )

static

Determines if the flush interval of a log has elapsed and flushes the buffer if needed.

This function calculates the difference between current time and log->last_flush. If it is greater than or equal to log->flush_time, the buffer is flushed.

Parameters

this_

The log object.

References dbg, log::flush_time, log_flush(), and lvl_debug.

Referenced by log_new().

log_write()

void log_write	(	struct log *	this_,
		char *	data,
		int	len,
		enum log_flags	flags
	)

Writes to a log.

This function appends data to a log. It rotates the log, if needed, before adding the new data. After adding, the log is flushed if the buffer exceeds its maximum size or if the log_flag_force_flush flag is set.

Parameters

this_	The log object.
data	Points to a buffer containing the data to be appended.
len	Length of the data to be appended, in bytes.
flags	Flags to control behavior of the function: log_flag_replace_buffer: discards any data in the buffer not yet written to the log file log_flag_force_flush: forces a flush of the log after appending the data {code log_flag_keep_pointer}: ignored log_flag_keep_buffer: ignored log_flag_truncate: ignored

References log_data::data, log::data, data, dbg, log_data::len, log_change(), log_change_required(), log_flag_force_flush, log_flag_replace_buffer, log_flush(), log_flush_required(), lvl_debug, lvl_info, and log_data::max_len.

Referenced by log_printf(), navit_textfile_debug_log(), navit_textfile_debug_log_at(), vehicle_log_binfile(), vehicle_log_gpx(), vehicle_log_nmea(), and vehicle_log_textfile().

strftime_localtime()

static void strftime_localtime ( char *  buffer, int  size, char *  fmt  )

static

Stores formatted time to a string.

This function obtains local system time, formats it as specified in fmt and stores it in buffer. Format strings follow the same syntax as those for strftime().

Parameters

buffer	A preallocated buffer that will receive the formatted time
size	Size of the buffer, in bytes
fmt	The format string

Returns

Nothing

References size.

Referenced by expand_filenames(), and log_change_required().

Variable Documentation

log_func

struct object_func log_func

Initial value:

= {
    attr_log,
    (object_func_new)log_new,
    (object_func_get_attr)navit_object_get_attr,
    (object_func_iter_new)navit_object_attr_iter_new,
    (object_func_iter_destroy)navit_object_attr_iter_destroy,
    (object_func_set_attr)navit_object_set_attr,
    (object_func_add_attr)navit_object_add_attr,
    (object_func_remove_attr)navit_object_remove_attr,
    (object_func_init)NULL,
    (object_func_destroy)log_destroy,
    (object_func_dup)NULL,
    (object_func_ref)navit_object_ref,
    (object_func_unref)navit_object_unref,
}

Referenced by log_new(), and object_func_lookup().