File: ms_log.3

package info (click to toggle)
libmseed 2.19.6-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster
  • size: 1,684 kB
  • sloc: ansic: 10,810; makefile: 145; sh: 114
file content (125 lines) | stat: -rw-r--r-- 4,401 bytes parent folder | download | duplicates (2)
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