Error reporting functions

Functions for reporting errors encountered by either a specific metric or an entire metric plugin library.

void allinea_set_plugin_error_message(plugin_id_t_t plugin_id, int error_code, const char * error_message)

Reports an error that occurred in the plugin (group of metrics).

void allinea_set_plugin_error_message ( plugin_id_t_t     metric_id,
                                             int           error_code,
                                             const char *  error_message
                                      )

This method takes a plain text string as its error_message. Instead, use allinea_set_plugin_error_messagef() to include specific details in the string using printf-style substitution.

This method must only be called from within allinea_plugin_initialise(), and only if the plugin library is not able to provide its data (for example if the required interfaces are not present or supported by the system).

Parameters

Parameter	Description
`plugin_id`	The id identifying the plugin that has encountered an error. The appropriate value is previously passed in as an argument to the allinea_plugin_initialise() call.
`error_code`	An error code that can be used to distinguish between the possible errors that might have occurred. The exact value is up to the plugin author but each error condition must have its own unique error code. In the case of a failing libc function, the libc `errno` (from `<errno.h>`) might be appropriate, but a plugin-author-specified constant can also be used. Linaro recommends that you document the meaning of the possible error codes for the benefit of users of your plugin.
`error_message`	A text string describing the error in a human-readable form. In the case of a failing libc function, the value `strerror(errno)` might be appropriate, but a plugin-author-specified message can also be used.

void allinea_set_plugin_error_messagef (plugin_id_t_t plugin_id, int error_code, const char * error_message,...)

Reports that an error occurred in the plugin (group of metrics).

See plugin_id_t_t.

void allinea_set_plugin_error_messagef ( plugin_id_t_t        plugin_id,
                                                int           error_code*,
                                                const char *  error_message*
                                                            ...
                                       )

This method does printf-style substitutions to format values inside the error message.

This method must only be called from within allinea_plugin_initialise(), and only if the plugin library is not able to provide its data (for example, if the required interfaces are not present or supported by the system).

Parameters

Parameter	Description
`plugin_id`	The id identifying the plugin that has encountered an error. The appropriate value is previously passed in as an argument to the allinea_plugin_initialise() call.
`error_code`	An error code that can be used to distinguish between the possible errors that might have occurred. The exact value is up to the plugin author but each error condition must have its own unique error code. In the case of a failing libc function, the libc `errno` (from `<errno.h>`) might be appropriate, but a plugin-author-specified constant can also be used. The meaning of the possible error codes must be documented for the benefit of users of your plugin.
`error_message`	A text string describing the error in a human-readable form. In the case of a failing libc function, the value `strerror(errno)` might be appropriate, but a plugin-author-specified message can also be used. This can include printf-style substitution characters.
`...`	Zero or more values for substituting into the `error_message` string in the same manner as `printf`.

Examples

See custom1.c.

void allinea_set_metric_error_message (metric_id_t_t metric_id, int error_code, const char * error_message)

Reports that an error occurred when reading a metric.

See metric_id_t_t.

void allinea_set_metric_error_message ( metric_id_t_t     metric_id,
                                            int           error_code,
                                            const char *  error_message
                                      )

Parameters

Parameter	Description
`metric_id`	The id identifying the metric that has encountered an error. The appropriate value is passed in as an argument to the metric `getter` call.
`error_code`	A pointer to the start of the memory region to free. This must be previously allocated with `allinea_safe_malloc()`, `allinea_safe_realloc()`, or `allinea_safe_calloc()`.
`error_message`	A text string describing the error in a human-readable form. In the case of a failing libc function, the value `strerror(errno)` might be appropriate, but a plugin-author-specified message can also be used.

void allinea_set_metric_error_messagef (metric_id_t_t metric_id, int error_code, const char * error_message,...)

Reports that an error occurred when reading a metric.

See metric_id_t_t.

void allinea_set_metric_error_messagef ( metric_id_t_t    metric_id,
                                            int           error_code,
                                            const char *  error_message
                                                          ...
                                       )

This method uses printf-style substitutions to format values inside the error message.

Parameters

Parameter	Direction
`metric_id`	The id identifying the metric that has encountered an error. The appropriate value is previously passed in as an argument to the metric `getter` call.
`error_code`	An error code that can be used to distinguish between the possible errors that might have occurred. The exact value is up to the plugin author but each error condition must have its own unique error code. In the case of a failing libc function the libc `errno` (from `<errno.h>`) might be appropriate, but a plugin-author-specified constant can also be used. The meaning of the possible error codes must be documented for the benefit of users of your plugin.
`error_message`	A text string describing the error in a human-readable form. In the case of a failing libc function, the value `strerror(errno)` might be appropriate, but a plugin-author-specified message can also be used. This can include printf-style substitution characters.
`...`	Zero or more values to be substituted into the `error_message` string.

Examples

See custom1.c.