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 messgaes, 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 it's 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]);

         /* Diognostic message, "LOG: " will be prefixed */
         ms_log (1, "Diagnositc 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)