MSTL_PRINT(3)

💖 MSTL_PRINT(3) 💖

ok bestie, gather round, because we're talking about mstl_print — the Library Functions Manual entry for printing out MSTrace info. it's giving "let me tell you about your traces" energy and honestly? iconic. 🎀

---

✨ NAME ✨

mstl_print — Printing of MSTrace information. that's it, that's the whole job. printing. MSTrace. information. 💅

---

🌸 SYNOPSIS 🌸

#include <libmseed.h>

void   mstl_printtracelist ( MSTraceList *mstl, flag timeformat,
                             flag details, flag gaps );

void   mstl_printsynclist ( MSTraceList *mstl, char *dccid,
                            flag subsecond );

void   mstl_printgaplist ( MSTraceList *mstl, flag timeformat,
                           double *mingap, double *maxgap );

three functions, all void, all here to print. no cap. 🫶

---

🦋 DESCRIPTION 🦋

mstl_printtracelist 💖

so mstl_printtracelist prints a formatted list of the trace segments living inside the MSTraceList you hand it. if the details flag is greater than 0, you also get the sample rate and sample count printed for each trace — like a little bonus info drop. and if the gaps flag is greater than zero, it also prints the time gap from the previous segment. everything gets printed using ms_log(3) at level 0, so that's where your output is going, periodt.

mstl_printsynclist ⭐

mstl_printsynclist also prints a formatted list of the trace segments in the given MSTraceList, similar to mstl_printtracelist, BUT the format is a SYNC listing. fancy. if you supply a dccid string, it gets used together with the current system date to build the SYNC header line. and if the subsecond flag is true (non-zero), the time values in the SYNC lines will include full libmseed precision — otherwise they get truncated down to integer second values. so like, choose your own adventure: precise or rounded. 🙈

mstl_printgaplist 🎀

mstl_printgaplist prints a formatted list of the gaps between trace segments in the given MSTraceList. if mingap or maxgap is not NULL, their values will be enforced, and only gaps/overlaps matching their implied criteria get printed. filtering queen. 👑

the timeformat situation ⏰

the timeformat argument for both mstl_printtracelist and mstl_printgaplist controls the format of the resulting time strings. the possible formats are:

• 0 : SEED time format (2005,146,00:00:00.000000)
• 1 : ISO time format (2005-05-26T00:00:00.000000)
• 2 : Epoch time, seconds since the epoch (1117065600.00000000)

negative gaps, yes really 😭

both mstl_printtracelist and mstl_printgaplist represent time overlaps as negative gaps. and for a single sample overlap, the value of the gap is calculated as zero — which gets printed as "-0" or negative zero, specifically to indicate an overlap. it's not a bug, bestie, it's a signal. 💀

---

🌈 GAP/OVERLAP RULES 🌈

ok so this part matters, listen up:

the existence of gaps and overlaps is implicit in the structure of the MSTraceList. no special processing is done to detect gaps and overlaps in these routines. they just... know. iykyk.

the value of a gap is calculated as the difference between the time of the last sample before the gap and the time of the first sample after the gap. no sample 'coverage' time is included.

the value of an overlap is calculated as the time between two samples which represent the maximum amount of timeseries overlap.

⚠️ and here's the gotcha: when the traces in the MSTraceList include a small segment that is completely overlapped by another larger segment, the gap/overlap value will not be correct for either the smaller segment or the segment following it. so like, heads up. 🚨

---

👑 SEE ALSO 👑

• ms_intro(3)

---

💜 AUTHOR 💜

Chad Trabant IRIS Data Management Center

---

and that's the whole page, bestie!! this is the Libmseed API, dated 2008/11/21 — yeah it's been slaying since 2008, main character energy fr fr. now go print some traces. 🌸✨💅