NAME

       ms_log - Central logging facility for libmseed

SYNOPSIS

       #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                                          MS_LOG(3)