ple_defs.c File Reference

Configurable error and memory handling with default functions. More...

#include "ple_config_defs.h"
#include <assert.h>
#include <errno.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <sys/time.h>
#include "ple_defs.h"

Macros
#define	_(String)   (String)
#define	N_(String)   String
#define	textdomain(String)   (String)
#define	gettext(String)   (String)
#define	dgettext(Domain, String)   (String)
#define	dcgettext(Domain, String, Type)   (String)
#define	bindtextdomain(Domain, Directory)   (Domain)

Functions
int	ple_printf (const char *const format,...)
	Replacement for printf() with modifiable behavior. More...
ple_printf_t *	ple_printf_function_get (void)
	Returns function associated with the ple_printf() function. More...
void	ple_printf_function_set (ple_printf_t *const fct)
	Associates a vprintf() type function with the ple_printf() function. More...
void	ple_error (const char *const file_name, const int line_num, const int sys_error_code, const char *const format,...)
	Calls the error handler (set by ple_error_handler_set() or default). More...
ple_error_handler_t *	ple_error_handler_get (void)
	Returns the error handler associated with the ple_error() function. More...
void	ple_error_handler_set (ple_error_handler_t *handler)
	Associates an error handler with the ple_error() function. More...
void *	ple_mem_malloc (size_t ni, size_t size, const char *var_name, const char *file_name, int line_num)
	Allocate memory for ni elements of size bytes. More...
void *	ple_mem_realloc (void *ptr, size_t ni, size_t size, const char *var_name, const char *file_name, int line_num)
	Reallocate memory for ni elements of size bytes. More...
void *	ple_mem_free (void *ptr, const char *var_name, const char *file_name, int line_num)
	Free allocated memory. More...
void	ple_mem_functions_get (ple_mem_malloc_t **malloc_func, ple_mem_realloc_t **realloc_func, ple_mem_free_t **free_func)
	Return the function pointers associated with PLE's memory management. More...
void	ple_mem_functions_set (ple_mem_malloc_t *malloc_func, ple_mem_realloc_t *realloc_func, ple_mem_free_t *free_func)
	Associate functions to modifiy PLE's memory management. More...
double	ple_timer_wtime (void)
	Return Wall clock time. More...
double	ple_timer_cpu_time (void)
	Return CPU time. More...

Detailed Description

Configurable error and memory handling with default functions.

Macro Definition Documentation

_

#define _

(

String

)

(String)

bindtextdomain

#define bindtextdomain	(		Domain,
			Directory
	)		(Domain)

dcgettext

#define dcgettext	(		Domain,
			String,
			Type
	)		(String)

dgettext

#define dgettext	(		Domain,
			String
	)		(String)

gettext

#define gettext

(

String

)

(String)

N_

#define N_

(

String

)

String

textdomain

#define textdomain

(

String

)

(String)

Function Documentation

ple_error()

void ple_error	(	const char *const	file_name,
		const int	line_num,
		const int	sys_error_code,
		const char *const	format,
			...
	)

Calls the error handler (set by ple_error_handler_set() or default).

With the default error handler, an error message is output to stderr, and the current process exits with an EXIT_FAILURE code.

Parameters

[in]	file_name	name of source file from which error handler called.
[in]	line_num	line of source file from which error handler called.
[in]	sys_error_code	error code if error in system or libc call, 0 otherwise.
[in]	format	format string, as printf() and family.
[in]	...	variable arguments based on format string.

ple_error_handler_get()

ple_error_handler_t* ple_error_handler_get

(

void

)

Returns the error handler associated with the ple_error() function.

Returns

pointer to the error handler function.

ple_error_handler_set()

void ple_error_handler_set

(

ple_error_handler_t *

handler

)

Associates an error handler with the ple_error() function.

Parameters

[in]

handler

pointer to the error handler function.

ple_mem_free()

void* ple_mem_free	(	void *	ptr,
		const char *	var_name,
		const char *	file_name,
		int	line_num
	)

Free allocated memory.

This function calls free(), but adds tracing capabilities, and automatically calls the ple_error() errorhandler if it fails to free the corresponding memory. In case of a NULL pointer argument, the function simply returns.

Parameters

[in]	ptr	pointer to previous memory location (if NULL, ple_alloc() called).
[in]	var_name	allocated variable name string
[in]	file_name	name of calling source file
[in]	line_num	line number in calling source file

Returns

NULL pointer.

ple_mem_functions_get()

void ple_mem_functions_get	(	ple_mem_malloc_t **	malloc_func,
		ple_mem_realloc_t **	realloc_func,
		ple_mem_free_t **	free_func
	)

Return the function pointers associated with PLE's memory management.

All arguments are optional.

Parameters

[out]	malloc_func	pointer to ple_mem_malloc function pointer (or NULL).
[out]	realloc_func	pointer to ple_mem_realloc function pointer (or NULL).
[out]	free_func	pointer to ple_mem_free function pointer (or NULL).

ple_mem_functions_set()

void ple_mem_functions_set	(	ple_mem_malloc_t *	malloc_func,
		ple_mem_realloc_t *	realloc_func,
		ple_mem_free_t *	free_func
	)

Associate functions to modifiy PLE's memory management.

All arguments are optional, so the previously set functions pointers will not be modified if an argument value is NULL.

Parameters

[in]	malloc_func	ple_mem_malloc function pointer (or NULL).
[in]	realloc_func	ple_mem_realloc function pointer (or NULL).
[in]	free_func	ple_mem_free function pointer (or NULL).

ple_mem_malloc()

void* ple_mem_malloc	(	size_t	ni,
		size_t	size,
		const char *	var_name,
		const char *	file_name,
		int	line_num
	)

Allocate memory for ni elements of size bytes.

This function calls malloc(), but adds tracing capabilities, and automatically calls the ple_error() errorhandler if it fails to allocate the required memory.

Parameters

[in]	ni	number of elements.
[in]	size	element size.
[in]	var_name	allocated variable name string.
[in]	file_name	name of calling source file.
[in]	line_num	line number in calling source file.

Returns

pointer to allocated memory.

ple_mem_realloc()

void* ple_mem_realloc	(	void *	ptr,
		size_t	ni,
		size_t	size,
		const char *	var_name,
		const char *	file_name,
		int	line_num
	)

Reallocate memory for ni elements of size bytes.

This function calls realloc(), but adds tracing capabilities, and automatically calls the ple_error() errorhandler if it fails to allocate the required memory.

Parameters

[in]	ptr	pointer to previous memory location (if NULL, ple_alloc() called).
[in]	ni	number of elements.
[in]	size	element size.
[in]	var_name	allocated variable name string.
[in]	file_name	name of calling source file.
[in]	line_num	line number in calling source file.

Returns

pointer to reallocated memory.

ple_printf()

int ple_printf	(	const char *const	format,
			...
	)

Replacement for printf() with modifiable behavior.

This function calls vprintf() by default, or a function with similar arguments indicated by ple_printf_function_set().

Parameters

[in]	format	format string, as printf() and family.
[in]	...	variable arguments based on format string.

Returns

number of characters printed, not counting the trailing '\0' used to end output strings

ple_printf_function_get()

ple_printf_t* ple_printf_function_get

(

void

)

Returns function associated with the ple_printf() function.

Returns

pointer to the vprintf() or replacement function.

ple_printf_function_set()

void ple_printf_function_set

(

ple_printf_t *const

fct

)

Associates a vprintf() type function with the ple_printf() function.

Parameters

[in]

fct

pointer to a vprintf() type function.

ple_timer_cpu_time()

double ple_timer_cpu_time

(

void

)

Return CPU time.

Note that in the rare case that only the minimal C library clock() method is available (see ple_timer_cpu_time_method()), at least one of the ple_timer_...() functions (possibly this one) must be called upon program start for this function to be used. In addition, in this case, time may "loop" back to 0 every multiple of 2^size_t / CLOCKS_PER_SEC seconds.

Returns

current CPU time usage, or -1 if unable to compute.

ple_timer_wtime()

double ple_timer_wtime

(

void

)

Return Wall clock time.

Returns

elapsed time from first call of a function of the ple_timer_...() series, or -1 if unable to compute.