Loading...
Searching...
No Matches
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);
...
cpl_msg_set_domain_on
void cpl_msg_set_domain_on(void)
Attach the domain tag to output messages.
Definition cpl_msg.c:1299
cpl_msg_set_level
void cpl_msg_set_level(cpl_msg_severity verbosity)
Set verbosity level of output to terminal.
Definition cpl_msg.c:1091
cpl_msg_set_component_on
void cpl_msg_set_component_on(void)
Attach the component tag to output messages.
Definition cpl_msg.c:1350
cpl_msg_set_domain
void cpl_msg_set_domain(const char *name)
Set the domain name.
Definition cpl_msg.c:1409
cpl_msg_set_log_level
cpl_error_code cpl_msg_set_log_level(cpl_msg_severity verbosity)
Open and initialise a log file.
Definition cpl_msg.c:898

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>
}
cpl_msg_info_overwritable
void cpl_msg_info_overwritable(const char *component, const char *format,...)
Display an overwritable information message.
Definition cpl_msg.c:1713

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().