table of contents
MS_LOG(3) | Library Functions Manual | MS_LOG(3) |
NAME¶
ms_log - Central logging facility for libmseedSYNOPSIS¶
#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);
DESCRIPTION¶
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.
RETURN VALUES¶
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()
EXAMPLE¶
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); }
AUTHOR¶
Chad Trabant IRIS Data Management Center
2014/07/16 |