| MS_LOG(3) | Library Functions Manual | MS_LOG(3) |
ms_log - Central logging facility for libmseed
#include <libmseed.h>
int ms_log (int level, const char *format, ...);
int ms_log_l (MSLogParam *logp, int level, const char *format, ...);
void ms_loginit (void (*log_print)(char*), const char *logprefix,
void (*diag_print)(char*), const char *errprefix);
MSLogParam * ms_loginit_l (MSLogParam *logp,
void (*log_print)(char*), const char *logprefix,
void (*diag_print)(char*), const char *errprefix);
The ms_log functions are the central logging facility for all output from libmseed functions. They are also intended to be used by libmseed based programs if desired.
Three message levels are recognized:
0 : Normal log messages, printed using log_print with logprefix
1 : Diagnostic messages, printed using diag_print with logprefix
2+ : Error messages, printed using diag_print with errprefix
It is the task of the ms_log functions to format a message using printf conventions and pass the formatted string to the appropriate printing function (log_print or diag_print).
ms_log will process messages using the global logging parameters.
ms_log_l is a reentrant version of ms_log. It will use the logging parameters specified in the supplied MSLogParam struct. If logp is NULL global parameters will be used, this would be equivalent to a call to ms_log(). This is intended for use only when complicated logging schemes are desired, e.g. in a threaded application. Note that it is not possible to set thread specific logging parameters for the internal library functions because global parameters are used.
The ms_loginit functions are used to set the log and error printing functions and the log and error message prefixes used by the ms_log functions.
ms_loginit will operate on the global logging parameters.
ms_loginit_l is a reentrant version of ms_loginit. It will initialize or change the logging parameters specified in the MSLogParam struct. If logp is NULL a new MSLogParam struct will be allocated. A pointer to the created or re-initialized MSLogParam struct will be returned. The returned pointer is suitable for use with ms_log_l.
Use NULL for the print function pointers or the prefixes if they should not be changed from previously set or default values.
The default values for the logging parameters are:
log_print = fprintf (printing to standard out)
log_prefix = ""
diag_print = fprintf (printing to standard error)
err_prefix = "Error: "
By setting the printing functions it is possible to re-direct all of the output from these logging routines. This is useful when the libmseed based software is embedded in a system with its own logging facilities.
Most of the libmseed internal messages are logged at either the diagnostic or error level.
ms_log and ms_log_l return the number of characters formatted on success, and a negative value on error.
ms_loginit_l returns a pointer to the MSLogParam struct that it operated on. If the input MSLogParam struct is NULL a new struct will be allocated with malloc()
Unless a complicated logging scheme is needed most uses of this logging facility will be limited to the ms_loginit and ms_log functions.
An example of setting the printing functions:
#include <libmseed.h>
void log_print (const char *message);
void diag_print (const char *message);
main () {
ms_loginit (&log_print, "LOG: ", &diag_print, "ERR: ");
/* Normal log message, "LOG: " will be prefixed */
ms_log (0, "Normal log message for %s0, argv[0]);
/* Diagnostic message, "LOG: " will be prefixed */
ms_log (1, "Diagnostic message for %s0, argv[0]);
/* Error message, "ERR: " will be prefixed */
ms_log (2, "Error message for %s0, argv[0]);
}
void log_print (const char *message) {
/* Send message to external log message facility */
send_log(message);
}
void diag_print (const char *message) {
/* Send message to external error message facility */
send_error(message);
}
Chad Trabant IRIS Data Management Center
| 2014/07/16 |