Enumerations | |
| enum | _cpl_msg_severity_ |
| Messaging verbosity. More... | |
Functions | |
| cpl_error_code | cpl_msg_start (void) |
| Initialise the messaging system. More... | |
| void | cpl_msg_stop (void) |
| Turn the messaging system off. More... | |
| cpl_error_code | cpl_msg_log_on (cpl_msg_severity verbosity) |
| Open and initialise a log file. More... | |
| cpl_error_code | cpl_msg_log_off (void) |
| Close the current log file. More... | |
| const char * | cpl_msg_log_file (void) |
| Get the logfile name. More... | |
| void | cpl_msg_terminal_on (cpl_msg_severity verbosity) |
| Set verbosity level of output to terminal. More... | |
| cpl_msg_severity | cpl_msg_log_level (void) |
| Get current log verbosity level. More... | |
| cpl_msg_severity | cpl_msg_terminal_level (void) |
| Get current terminal verbosity level. More... | |
| void | cpl_msg_time_tag_on (void) |
| Attach a time tag to output messages. More... | |
| void | cpl_msg_time_tag_off (void) |
| Disable the time tag in output messages. More... | |
| void | cpl_msg_domain_tag_on (void) |
| Attach the domain tag to output messages. More... | |
| void | cpl_msg_domain_tag_off (void) |
| Disable the domain tag in output messages. More... | |
| void | cpl_msg_component_tag_on (void) |
| Attach the component tag to output messages. More... | |
| void | cpl_msg_component_tag_off (void) |
| Disable the component tag in output messages. More... | |
| void | cpl_msg_set_domain_tag (const char *name) |
| Set the domain name. More... | |
| void | cpl_msg_set_width (int width) |
| Set the maximum width of the displayed text. More... | |
| void | cpl_msg_set_indent_step (int step) |
| Set the indentation step. More... | |
| void | cpl_msg_indent (int level) |
| Set the indentation level. More... | |
| void | cpl_msg_indent_more (void) |
| Increase the message indentation by one indentation step. More... | |
| void | cpl_msg_indent_less (void) |
| Decrease the message indentation by one indentation step. More... | |
| void | cpl_msg_error (const char *component, char *format,...) |
| Display an error message. More... | |
| void | cpl_msg_warning (const char *component, char *format,...) |
| Display a warning message. More... | |
| void | cpl_msg_info (const char *component, char *format,...) |
| Display an information message. More... | |
| void | cpl_msg_debug (const char *component, char *format,...) |
| Display a debug message. More... | |
cpl_msg_start() and cpl_msg_stop() must be used. These functions will typically be called at the beginning and at the end of a program. An attempt to use an uninitialised messaging system would generate an assertion failure. More functions may also be used to configure the messaging system, and here is an example of a possible initialisation:
...
cpl_msg_start();
cpl_msg_terminal_on(CPL_MSG_ERROR);
cpl_msg_log_on(CPL_MSG_DEBUG);
cpl_msg_time_tag_on();
cpl_msg_component_tag_on();
cpl_msg_set_domain_tag("Source detection");
cpl_msg_domain_tag_on();
...
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_time_tag_on() and cpl_msg_time_tag_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_domain_tag_on() and cpl_msg_domain_tag_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_component_tag_on() and cpl_msg_component_tag_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 logfile. 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 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_indent_step().
#include <cpl_messaging.h>
|
|
Messaging verbosity.
Messages may be printed with any of the functions |
|
|
Disable the component tag in output messages.
CPL_MSG_DEBUG. The component tag cannot be turned off in messages written to the logfile. |
|
|
Attach the component tag to output messages.
cpl_msg_component_tag_off() should be called. However, the component tag is always shown when the verbosity level is set to CPL_MSG_DEBUG. |
|
||||||||||||||||
|
Display a debug message.
cpl_msg_error(). |
|
|
Disable the domain tag in output messages.
|
|
|
Attach the domain tag to output messages.
cpl_msg_domain_tag_off() must be called. |
|
||||||||||||||||
|
Display an error message.
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 or format are NULL pointers, and assertion failure would be generated. |
|
|
Set the indentation level.
cpl_msg_set_indent_step(). Specifying a negative indentation level would set the indentation level to zero. |
|
|
Decrease the message indentation by one indentation step.
|
|
|
Increase the message indentation by one indentation step.
cpl_msg_indent(). |
|
||||||||||||||||
|
Display an information message.
cpl_msg_error(). |
|
|
Get the logfile name.
|
|
|
Get current log verbosity level.
|
|
|
Close the current log file.
cpl_msg_log_file(). An attempt to close a non existing logfile would not generate an error condition. Typically this routine is called at the end of a program. |
|
|
Open and initialise a log file.
cpl_msg_set_domain_tag(), 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 logfile is always the same, and can be obtained by calling the function cpl_msg_log_file(). Typically this function is called at the beginning of a program. Calling it while a logfile is already open has no effect, but it will return an error code. |
|
|
Set the domain name.
cpl_msg_domain_tag_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_domain_tag_off() should be called. If $em name is a NULL pointer, an assertion failure is generated. |
|
|
Set the indentation step.
|
|
|
Set the maximum width of the displayed text.
|
|
|
Initialise the messaging system.
cpl_msg_stop(). Currently just the terminal width is determined (if possible), and the resized window signal handler is deployed to monitor possible changes of the terminal window width. The stdout and stderr streams are duplicated for greater flexibility of the system. |
|
|
Turn the messaging system off.
cpl_msg_start() should be 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 set to CPL_MSG_OFF. |
|
|
Get current terminal verbosity level.
|
|
|
Set verbosity level of output to terminal.
CPL_MSG_INFO. |
|
|
Disable the time tag in output messages.
|
|
|
Attach a time tag to output messages.
cpl_msg_time_tag_off() should be called. |
|
||||||||||||||||
|
Display a warning message.
cpl_msg_error(). |
1.2.14 written by Dimitri van Heesch,
© 1997-2002