MS_LOG(3)

💖 MS_LOG(3) — the libmseed logging facility, bestie 💖

okay so hi, you found the page for ms_log, and honestly? it's giving central logging facility for libmseed. It lives in the Library Functions Manual section 3 (you know, the library functions girlies), so pull up a chair, grab a strawberry 🍓, and let's get into it.

---

🌸 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 🦋

So the ms_log functions are THE central logging facility for all output from libmseed functions. Periodt. They're also meant to be used by libmseed based programs if you want to, no pressure 💅

There are three message levels recognized, and yes you need to know them:

• 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

The whole job of the ms_log functions is to format a message using printf conventions and then pass that formatted string over to the appropriate printing function (log_print or diag_print). Simple, iconic, no notes.

ms_log will process messages using the global logging parameters.

ms_log_l is a reentrant version of ms_log. It uses the logging parameters specified in the supplied MSLogParam struct. If logp is NULL, global parameters will be used — which would be equivalent to a call to ms_log(). This one is intended for use only when complicated logging schemes are desired, e.g. in a threaded application. And bestie, heads up: it is not possible to set thread specific logging parameters for the internal library functions, because global parameters are used. iykyk 😭

The ms_loginit functions are how you set the log and error printing functions, plus 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. That 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. Chef's kiss, honestly 👑

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. Very demure, very mindful.

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

---

okay that's the whole page, you ate it, no crumbs 💅

and that's a wrap bestie — this page is from MS_LOG(3), dated 2014/07/16, and it's part of the Library Functions Manual. Go forth and log responsibly 🦋✨💖