Messages

Functions
void	cpl_msg_debug (const char *component, const char *format,...)
	Display a debug message.
void	cpl_msg_error (const char *component, const char *format,...)
	Display an error message.
const char *	cpl_msg_get_domain (void)
	Get the domain name.
cpl_msg_severity	cpl_msg_get_level (void)
	Get current terminal verbosity level.
cpl_msg_severity	cpl_msg_get_log_level (void)
	Get current log verbosity level.
const char *	cpl_msg_get_log_name (void)
	Get the log file name.
void	cpl_msg_indent (int level)
	Set the indentation level.
void	cpl_msg_indent_less (void)
	Decrease the message indentation by one indentation step.
void	cpl_msg_indent_more (void)
	Increase the message indentation by one indentation step.
void	cpl_msg_info (const char *component, const char *format,...)
	Display an information message.
void	cpl_msg_info_overwritable (const char *component, const char *format,...)
	Display an overwritable information message.
cpl_error_code	cpl_msg_init (void)
	Initialise the messaging system.
void	cpl_msg_progress (const char *component, int i, int iter, const char *format,...)
	Display a progress message predicting the time required in a loop.
void	cpl_msg_set_component_off (void)
	Disable the component tag in output messages.
void	cpl_msg_set_component_on (void)
	Attach the component tag to output messages.
void	cpl_msg_set_domain (const char *name)
	Set the domain name.
void	cpl_msg_set_domain_off (void)
	Disable the domain tag in output messages.
void	cpl_msg_set_domain_on (void)
	Attach the domain tag to output messages.
void	cpl_msg_set_indentation (int step)
	Set the indentation step.
void	cpl_msg_set_level (cpl_msg_severity verbosity)
	Set verbosity level of output to terminal.
void	cpl_msg_set_level_from_env (void)
	Set verbosity level of terminal output using an environment variable.
cpl_error_code	cpl_msg_set_log_level (cpl_msg_severity verbosity)
	Open and initialise a log file.
cpl_error_code	cpl_msg_set_log_name (const char *name)
	Set the log file name.
void	cpl_msg_set_threadid_off (void)
	Disable the thread id tag to output messages.
void	cpl_msg_set_threadid_on (void)
	Attach a thread id tag to output messages.
void	cpl_msg_set_time_off (void)
	Disable the time tag in output messages.
void	cpl_msg_set_time_on (void)
	Attach a time tag to output messages.
void	cpl_msg_set_width (int width)
	Set the maximum width of the displayed text.
void	cpl_msg_stop (void)
	Turn the messaging system off.
cpl_error_code	cpl_msg_stop_log (void)
	Close the current log file.
void	cpl_msg_warning (const char *component, const char *format,...)
	Display a warning message.

Detailed Description

This module provides functions to display and log messages. The following operations are supported:

- Enable messages output to terminal or to log file.
- Optionally adding informative tags to messages.
- Setting width for message line wrapping.
- Control the message indentation level.
- Filtering messages according to their severity level.

To activate and deactivate the messaging system, the functions cpl_msg_init() and cpl_msg_stop() need to be used. However, since they are called anyway by the functions cpl_init() and cpl_end(), there is generally no need to call them explicitly, and starting from CPL 2.1 they are deprecated. These functions would typically be called at the beginning and at the end of a program. An attempt to use an uninitialised messaging system would generate a warning message. More functions may also be used to configure the messaging system, and here is an example of a possible initialisation:

...
cpl_msg_set_time_on();
cpl_msg_set_component_on();
cpl_msg_set_domain("Source detection");
cpl_msg_set_domain_on();
cpl_msg_set_level(CPL_MSG_ERROR);
cpl_msg_set_log_level(CPL_MSG_DEBUG);
...

The functions of these kind, are meant to configure the messaging system, defining its "style", once and for all. For this reason such functions are not supposed to be called from threads. Three different tags may be attached to any message: time, domain, and component. The time tag is the time of printing of the message, and can optionally be turned on or off with the functions cpl_msg_set_time_on() and cpl_msg_set_time_off(). The domain tag is an identifier of the main program running (typically, a pipeline recipe), and can be optionally turned on or off with the functions cpl_msg_set_domain_on() and cpl_msg_set_domain_off(). Finally, the component tag is used to identify a component of the program running (typically, a function), and can be optionally turned on or off with the functions cpl_msg_set_component_on() and cpl_msg_set_component_off(). As a default, none of the above tags are attached to messages sent to terminal. However, all tags are always used in messages sent to the log file. A further tag, the severity tag, can never be turned off. This tag depends on the function used to print a message, that can be either cpl_msg_debug(), cpl_msg_info(), cpl_msg_warning(), or cpl_msg_error(). The time and severity tags are all prepended to any message, and are not affected by the message indentation controlled by the functions cpl_msg_indent(), cpl_msg_indent_more(), cpl_msg_indent_less(), and cpl_msg_set_indentation().

Synopsis:

#include <cpl_msg.h>

Function Documentation

cpl_msg_debug()

void cpl_msg_debug	(	const char *	component,
		const char *	format,
			...
	)

Display a debug message.

Returns

Nothing.

Parameters

component	Name of the function generating the message.
format	Format string.
...	Variable argument list associated to the format string.

See the description of the function cpl_msg_error().

References cpl_msg_debug().

Referenced by cpl_errorstate_dump_one_debug(), cpl_frameset_labelise(), cpl_geom_img_offset_fine(), cpl_msg_debug(), cpl_msg_progress(), cpl_ppm_match_points(), and cpl_test_end().

cpl_msg_error()

void cpl_msg_error	(	const char *	component,
		const char *	format,
			...
	)

Display an error message.

Returns

Nothing.

Parameters

component	Name of the component generating the message.
format	Format string.
...	Variable argument list associated to the format string.

The format string should follow the usual printf() convention. Newline characters shouldn't generally be used, as the message would be split automatically according to the width specified with cpl_msg_set_width(). Inserting a newline character would enforce breaking a line of text even before the current row is filled. Newline characters at the end of the format string are not required. If component is a NULL pointer, it would be set to the string "<empty field>". If format is a NULL pointer, the message "<empty message>" would be printed.

References cpl_msg_error().

Referenced by cpl_errorstate_dump(), cpl_errorstate_dump_one(), cpl_msg_error(), and cpl_test_end().

cpl_msg_get_domain()

const char * cpl_msg_get_domain

(

void

)

Get the domain name.

Returns

Pointer to "domain" string.

This routine returns always the same pointer to the statically allocated buffer containing the "domain" string.

cpl_msg_get_level()

cpl_msg_severity cpl_msg_get_level

(

void

)

Get current terminal verbosity level.

Returns

Current verbosity level.

Get current verbosity level set for the output to terminal.

Referenced by cpl_test_end().

cpl_msg_get_log_level()

cpl_msg_severity cpl_msg_get_log_level

(

void

)

Get current log verbosity level.

Returns

Current verbosity level.

Get current verbosity level set for the output to the log file.

cpl_msg_get_log_name()

const char * cpl_msg_get_log_name

(

void

)

Get the log file name.

Returns

Logfile name

The name of the log file is returned.

Referenced by cpl_test_end().

cpl_msg_indent()

void cpl_msg_indent

(

int

level

)

Set the indentation level.

Returns

Nothing.

Parameters

level

Indentation level.

Any message printed after a call to this function would be indented by a number of characters equal to the level multiplied by the indentation step specified with the function cpl_msg_set_indentation(). Specifying a negative indentation level would set the indentation level to zero.

cpl_msg_indent_less()

void cpl_msg_indent_less

(

void

)

Decrease the message indentation by one indentation step.

Returns

Nothing.

Calling this function is equivalent to decrease the indentation level by 1. If the indentation level is already 0, it is not decreased.

Referenced by cpl_ppm_match_points(), and cpl_test_end().

cpl_msg_indent_more()

void cpl_msg_indent_more

(

void

)

Increase the message indentation by one indentation step.

Returns

Nothing.

Calling this function is equivalent to increase the indentation level by 1. See function cpl_msg_indent().

Referenced by cpl_ppm_match_points(), and cpl_test_end().

cpl_msg_info()

void cpl_msg_info	(	const char *	component,
		const char *	format,
			...
	)

Display an information message.

Returns

Nothing.

Parameters

component	Name of the function generating the message.
format	Format string.
...	Variable argument list associated to the format string.

See the description of the function cpl_msg_error().

References cpl_msg_info().

Referenced by cpl_errorstate_dump_one_info(), cpl_msg_info(), cpl_msg_info_overwritable(), and cpl_test_end().

cpl_msg_info_overwritable()

void cpl_msg_info_overwritable	(	const char *	component,
		const char *	format,
			...
	)

Display an overwritable information message.

Returns

Nothing.

Parameters

component	Name of the function generating the message.
format	Format string.
...	Variable argument list associated to the format string.

See the description of the function cpl_msg_error(). The severity of the message issued by cpl_msg_info_overwritable() is the same as the severity of a message issued using cpl_msg_info(). The only difference with the cpl_msg_info() function is that the printed message would be overwritten by a new message issued using again cpl_msg_info_overwritable(), if no other meassages were issued with other messaging functions in between. This function would be used typically in loops, as in the following example:

iter = 1000;
for (i = 0; i < iter; i++) {
    cpl_msg_info_overwritable(cpl_func,
                   "Median computation... %d out of %d", i, iter);
    <median computation would take place here>
}

Note

In the current implementation, an overwritable message is obtained by not adding the new-line character ('\n') at the end of the message (contrary to what cpl_msg_info() does).

References cpl_msg_info().

cpl_msg_init()

cpl_error_code cpl_msg_init

(

void

)

Initialise the messaging system.

Returns

CPL_ERROR_NONE on success.

Errors

CPL_ERROR_FILE_ALREADY_OPEN	The messaging system was already initialised.
CPL_ERROR_DUPLICATING_STREAM	stdout and stderr streams cannot be duplicated.
CPL_ERROR_ASSIGNING_STREAM	A stream cannot be associated with a file descriptor.

This function needs to be called to activate the messaging system, typically at the beginning of a program. An attempt to use any messaging function before turning the system on would generate a warning message. The messaging system needs to be deactivated by calling the function cpl_msg_stop(). However, since these functions are called anyway by the functions cpl_init() and cpl_end(), there is generally no need to call them explicitly, and starting from CPL 2.1 they are deprecated.

When cpl_msg_init() is called, the stdout and stderr streams are duplicated for greater flexibility of the system. The terminal width is determined (if possible), and the resized window signal handler is deployed to monitor possible changes of the terminal window width. If the width of the output device cannot be determined, lines of text are not splitted when written to output. If line splitting is not wanted, the function cpl_msg_set_width() should be called specifying a non positive width.

References CPL_ERROR_ASSIGNING_STREAM, CPL_ERROR_DUPLICATING_STREAM, CPL_ERROR_FILE_ALREADY_OPEN, and CPL_ERROR_NONE.

Referenced by cpl_init().

cpl_msg_progress()

void cpl_msg_progress	(	const char *	component,
		int	i,
		int	iter,
		const char *	format,
			...
	)

Display a progress message predicting the time required in a loop.

Returns

Nothing.

Parameters

component	Name of the function generating the message.
i	Iteration, starting with 0 and less than iter.
iter	Total number of iterations.
format	Format string.
...	Variable argument list associated to the format string.

See also

cpl_msg_info()

Deprecated:

Use standard calls such as cpl_msg_info() instead.

References cpl_free(), cpl_msg_debug(), and cpl_sprintf().

cpl_msg_set_component_off()

void cpl_msg_set_component_off

(

void

)

Disable the component tag in output messages.

Returns

Nothing.

The component tag is turned off in messages written to terminal, unless the verbosity level is set to CPL_MSG_DEBUG. The component tag cannot be turned off in messages written to the log file.

Note

This function is meant to configure once and for all the behaviour and the "style" of the messaging system, and it is not supposed to be called in threads.

cpl_msg_set_component_on()

void cpl_msg_set_component_on

(

void

)

Attach the component tag to output messages.

Returns

Nothing.

As a default, the component tag is attached just to messages written to the log file. This function must be called to display the component tag also in messages written to terminal. To turn the component tag off the function cpl_msg_set_component_off() should be called. However, the component tag is always shown when the verbosity level is set to CPL_MSG_DEBUG.

Note

This function is meant to configure once and for all the behaviour and the "style" of the messaging system, and it is not supposed to be called in threads.

cpl_msg_set_domain()

void cpl_msg_set_domain

(

const char *

name

)

Set the domain name.

Parameters

name	Any task identifier, typically a pipeline recipe name.

Returns

Nothing.

This routine should be called at a pipeline recipe start, and before a possible call to the function cpl_msg_set_log_level() or the proper task identifier would not appear in the log file header. The domain tag is attached to messages sent to terminal only if the function cpl_msg_set_domain_on() is called. If the domain tag is on and no domain tag was specified, the string "Undefined domain" (or something analogous) would be attached to all messages. To turn the domain tag off the function cpl_msg_set_domain_off() should be called. If name is a NULL pointer, nothing is done, and no error is set.

Note

This function is meant to configure once and for all the behaviour and the "style" of the messaging system, and it is not supposed to be called in threads.

cpl_msg_set_domain_off()

void cpl_msg_set_domain_off

(

void

)

Disable the domain tag in output messages.

Returns

Nothing.

The domain tag is turned off in messages written to terminal.

Note

This function is meant to configure once and for all the behaviour and the "style" of the messaging system, and it is not supposed to be called in threads.

cpl_msg_set_domain_on()

void cpl_msg_set_domain_on

(

void

)

Attach the domain tag to output messages.

Returns

Nothing.

As a default, the domain tag is just written to the header of the log file. This function must be called to attach the domain tag to all messages written to terminal. If the domain tag is on and no domain tag was specified, the string "Undefined domain" (or something analogous) would be attached to all messages. To turn the domain tag off the function cpl_msg_set_domain_off() must be called.

Note

This function is meant to configure once and for all the behaviour and the "style" of the messaging system, and it is not supposed to be called in threads.

cpl_msg_set_indentation()

void cpl_msg_set_indentation

(

int

step

)

Set the indentation step.

Parameters

step	Indentation step.

Returns

Nothing.

To maintain a consistent message display style, this routine should be called at most once, and just at program start. A message line might be moved leftward or rightward by a number of characters that is a multiple of the specified indentation step. Setting the indentation step to zero or to a negative number would eliminate messages indentation. If this function is not called, the indentation step defaults to 2.

Note

This function is meant to configure once and for all the behaviour and the "style" of the messaging system, and it is not supposed to be called in threads.

cpl_msg_set_level()

void cpl_msg_set_level

(

cpl_msg_severity

verbosity

)

Set verbosity level of output to terminal.

Parameters

verbosity

Verbosity level.

Returns

Nothing.

The verbosity specifies the lowest severity level that a message should have for being displayed to terminal. If this function is not called, the verbosity level defaults to CPL_MSG_INFO.

Note

This function is not supposed to be called in threads.

Referenced by cpl_msg_set_level_from_env(), and cpl_test_end().

cpl_msg_set_level_from_env()

void cpl_msg_set_level_from_env

(

void

)

Set verbosity level of terminal output using an environment variable.

Returns

void

See also

cpl_msg_set_level

Note

This function can be used for run-time control of the verbosity level of unit test modules.

The CPL verbosity level of output to terminal is set according to the environment variable CPL_MSG_LEVEL: debug: CPL_MSG_DEBUG info: CPL_MSG_INFO warning: CPL_MSG_WARNING error: CPL_MSG_ERROR off: CPL_MSG_OFF

Any other value (including NULL) will cause the function to do nothing.

References cpl_msg_set_level().

cpl_msg_set_log_level()

cpl_error_code cpl_msg_set_log_level

(

cpl_msg_severity

verbosity

)

Open and initialise a log file.

Parameters

verbosity

Verbosity level.

Returns

CPL_ERROR_NONE on success.

Errors

CPL_ERROR_FILE_ALREADY_OPEN	A log file was already started.
CPL_ERROR_FILE_NOT_CREATED	Log file cannot be created.

If the specified verbosity level is different from CPL_MSG_OFF, a log file is created and initialised with a header containing the start logging time, the domain identifier set by the function cpl_msg_set_domain(), and the chosen verbosity level. The verbosity specifies the lowest severity level that a message should have to be written to the log file. The name of the created log file may be previously set with the function cpl_msg_set_log_name(), otherwise it is left to a default ".logfile". The log file name can be obtained by calling the function cpl_msg_get_log_name(). Typically this function is called at the beginning of a program. Calling it while a log file is already open has no effect, but it will return an error code.

Note

This function is meant to configure once and for all the behaviour and the "style" of the messaging system, and it is not supposed to be called in threads.

References CPL_ERROR_FILE_ALREADY_OPEN, CPL_ERROR_FILE_NOT_CREATED, and CPL_ERROR_NONE.

cpl_msg_set_log_name()

cpl_error_code cpl_msg_set_log_name

(

const char *

name

)

Set the log file name.

Parameters

name	Name of log file.

Returns

CPL_ERROR_NONE on success.

Errors

CPL_ERROR_NULL_INPUT	The specified name is a NULL pointer.
CPL_ERROR_FILE_ALREADY_OPEN	A log file was already started.
CPL_ERROR_ILLEGAL_INPUT	The specified name is longer than CPL_MAX_LOGFILE_NAME characters (including the terminating '\0').

This function is used to set the log file name, and can only be called before the log is opened by cpl_msg_set_log_level(). If this function is not called, or the specified name is longer than CPL_MAX_LOGFILE_NAME characters, the log file name is left to its default, ".logfile".

Note

This function is meant to configure once and for all the behaviour and the "style" of the messaging system, and it is not supposed to be called in threads.

References CPL_ERROR_FILE_ALREADY_OPEN, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

cpl_msg_set_threadid_off()

void cpl_msg_set_threadid_off

(

void

)

Disable the thread id tag to output messages.

Returns

Nothing.

The thread id tag is turned off in messages written to terminal. The thread id tag cannot be turned off in messages written to the log file.

Note

This function is meant to configure once and for all the behaviour and the "style" of the messaging system, and it is not supposed to be called in threads.

cpl_msg_set_threadid_on()

void cpl_msg_set_threadid_on

(

void

)

Attach a thread id tag to output messages.

Returns

Nothing.

As a default, thread ids tags are attached just to messages written to the log file. This function must be called to display the thread id tag also in messages written to terminal. To turn the thread id tag off the function cpl_msg_set_threadid_off() should be called.

Note

This function is meant to configure once and for all the behaviour and the "style" of the messaging system, and it is not supposed to be called in threads.

cpl_msg_set_time_off()

void cpl_msg_set_time_off

(

void

)

Disable the time tag in output messages.

Returns

Nothing.

The time tag is turned off in messages written to terminal. The time tag cannot be turned off in messages written to the log file.

Note

This function is meant to configure once and for all the behaviour and the "style" of the messaging system, and it is not supposed to be called in threads.

cpl_msg_set_time_on()

void cpl_msg_set_time_on

(

void

)

Attach a time tag to output messages.

Returns

Nothing.

As a default, time tags are attached just to messages written to the log file. This function must be called to display the time tag also in messages written to terminal. To turn the time tag off the function cpl_msg_set_time_off() should be called.

Note

This function is meant to configure once and for all the behaviour and the "style" of the messaging system, and it is not supposed to be called in threads.

cpl_msg_set_width()

void cpl_msg_set_width

(

int

width

)

Set the maximum width of the displayed text.

Parameters

width

Max width of the displayed text.

Returns

Nothing.

If a message is longer than width characters, it would be broken into shorter lines before being displayed to terminal. However, words longer than width would not be broken, and in this case longer lines would be printed. This function is automatically called by the messaging system every time the terminal window is resized, and the width is set equal to the new width of the terminal window. If width is zero or negative, long message lines would not be broken. Lines are never broken in log files.

cpl_msg_stop()

void cpl_msg_stop

(

void

)

Turn the messaging system off.

Returns

Nothing

This function needs to be called to turn the messaging system off, typically at the end of a program. To turn the messaging system on the function cpl_msg_init() needs to be called. However, since these functions are called anyway by the functions cpl_init() and cpl_end(), there is generally no need to call them explicitly, and starting from CPL 2.1 they are deprecated.

When cpl_msg_stop() is called, the default resized window signal handler is restored, and the duplicated output streams are closed. If a log file is still open, it is closed, and the log verbosity level is set to CPL_MSG_OFF. If the messaging system is not on, nothing is done, and no error is set.

References cpl_msg_stop_log().

Referenced by cpl_end().

cpl_msg_stop_log()

cpl_error_code cpl_msg_stop_log

(

void

)

Close the current log file.

Returns

CPL_ERROR_NONE on success.

The log file is closed. The name of the created log file is always the same, and can be obtained by calling the function cpl_msg_get_log_name(). An attempt to close a non existing log file would not generate an error condition. This routine may be called in case the logging should be terminated before the end of a program. Otherwise, the function cpl_msg_stop() would automatically close the log file when called at the end of the program.

References CPL_ERROR_NONE.

Referenced by cpl_msg_stop().

cpl_msg_warning()

void cpl_msg_warning	(	const char *	component,
		const char *	format,
			...
	)

Display a warning message.

Returns

Nothing.

Parameters

component	Name of the function generating the message.
format	Format string.
...	Variable argument list associated to the format string.

See the description of the function cpl_msg_error().

References cpl_msg_warning().

Referenced by cpl_dfs_setup_product_header(), cpl_errorstate_dump_one_warning(), cpl_get_description(), cpl_init(), cpl_msg_warning(), cpl_property_delete(), and cpl_test_end().