1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
|
.TH MS_LOG 3 2014/07/16
.SH NAME
ms_log - Central logging facility for libmseed
.SH SYNOPSIS
.nf
.B #include <libmseed.h>
.sp
.BI "int \fBms_log\fP (int " level ", const char *" format ", ...);
.sp
.BI "int \fBms_log_l\fP (MSLogParam *" logp ", int " level ", const char *" format ", ...);
.sp
.BI "void \fBms_loginit\fP (void (*" log_print ")(char*), const char *" logprefix ",
.BI " void (*" diag_print ")(char*), const char *" errprefix ");
.sp
.BI "MSLogParam * \fBms_loginit_l\fP (MSLogParam *" logp ",
.BI " void (*" log_print ")(char*), const char *" logprefix ",
.BI " void (*" diag_print ")(char*), const char *" errprefix ");
.fi
.SH DESCRIPTION
The \fBms_log\fP 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 \fBms_log\fP functions to format a message using
\fBprintf\fP conventions and pass the formatted string to the
appropriate printing function (\fIlog_print\fP or \fIdiag_print\fP).
\fBms_log\fP will process messages using the global logging
parameters.
\fBms_log_l\fP is a reentrant version of \fBms_log\fP. It will use
the logging parameters specified in the supplied MSLogParam struct.
If \fBlogp\fP 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 \fBms_loginit\fP functions are used to set the log and error
printing functions and the log and error message prefixes used by the
\fBms_log\fP functions.
\fBms_loginit\fP will operate on the global logging parameters.
\fBms_loginit_l\fP is a reentrant version of \fBms_loginit\fP. It
will initialize or change the logging parameters specified in the
MSLogParam struct. If \fIlogp\fP 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
\fBms_log_l\fP.
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.
.SH RETURN VALUES
\fBms_log\fP and \fBms_log_l\fP return the number of characters
formatted on success, and a negative value on error.
\fBms_loginit_l\fP 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 \fBmalloc()\bP.
.SH 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:
.nf
#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 %s\n", argv[0]);
/* Diagnostic message, "LOG: " will be prefixed */
ms_log (1, "Diagnostic message for %s\n", argv[0]);
/* Error message, "ERR: " will be prefixed */
ms_log (2, "Error message for %s\n", 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);
}
.fi
.SH AUTHOR
.nf
Chad Trabant
IRIS Data Management Center
.fi
|