MST_ADDMSR(3)

💖 MST_ADDMSR(3) — the libmseed girlies' guide to feeding your MSTrace 💖

okay bestie, so this is a page from the Library Functions Manual, and it's literally all about the mst_addmsr family — four little functions that glue time coverage and data samples onto MSTrace structures. no cap, it's giving "plumbing but make it cute" 🫶

✨ NAME ✨

mst_addmsr — adds time coverage and data samples to MSTrace structures. that's it, that's the vibe 💅

🌸 SYNOPSIS 🌸

#include <libmseed.h>

int    *mst_addmsr ( MSTrace *mst, MSRecord *msr, flag whence );

int     mst_addspan ( MSTrace *mst, hptime_t starttime, hptime_t endtime,
                      void *datasamples, int64_t numsamples,
                      char sampletype,  flag whence );

MSTrace  *mst_addmsrtogroup ( MSTraceGroup *mstg, MSRecord *msr,
                              flag dataquality, double timetol,
                              double sampratetol );

MSTrace  *mst_addtracetogroup ( MSTraceGroup *mstg, MSTrace *mst );

like… four functions, four signatures, all of them iconic in their own way ✨

🦋 DESCRIPTION 🦋

so these routines are basically different flavors of "add time coverage to your MSTrace objects". and a very common way to organize MSTrace objects is with a MSTraceGroup — think of it like a group chat but for traces 💬. and mst_addmsrtogroup is the convenience queen that lets you add MSRecord data into a MSTraceGroup while hiding, like, so many of the messy details of MSTrace matching and bookkeeping. she does the admin work for you, periodt 👑

mst_addmsr adds the time coverage from a MSRecord to a MSTrace. the start or end time gets updated, and data samples get copied if they exist. and here's the tea: no checking is done to verify that the record matches the trace in any way. none. zero. it's giving "trust fall" 🙈. if whence is 1, the MSRecord coverage gets added at the end of the MSTrace. if whence is 2, the MSRecord coverage gets added at the beginning of the MSTrace.

mst_addspan does the exact same thing as msr_addmsr except that time coverage and data samples are explicitly provided by you. you'll wanna peek at ms_time(3) for the deets on the high precision epoch time format needed for starttime and endtime. and for how data samples are represented, check the Waveform Data section of ms_intro(3) 🌊.

mst_addmsrtogroup adds time coverage from the specified MSRecord to the first adjacent MSTrace found in the specified MSTraceGroup. if the dataquality flag is true, traces get grouped by quality in addition to the source name identifiers (yes, both, she's thorough 💅). mst_findadjacent(3) is used with the specified sample rate and time tolerances to find an adjacent trace — go read mst_findadjacent(3) for further details, iykyk. and if no adjacent MSTrace is found? a brand new MSTrace gets added to the MSTraceGroup. slay, growth mindset 🌱

mst_addtracetogroup adds a MSTrace structure to a MSTraceGroup structure. the MSTrace is added at the end of the MSTrace chain. simple. clean. iconic.

💀 RETURN VALUES 💀

• mst_addmsr and mst_addspan return 0 on success and -1 on error. that's the whole mood — zero for yes, negative one for nope 😭
• mst_addmsrtogroup returns a pointer to the MSTrace updated, or 0 on error.
• mst_addtracetogroup returns a pointer to the MSTrace added, or 0 on error.

fr fr, watch those 0 returns on the pointer-returning ones — 0 here means error, not "a trace that is literally zero". don't get got 🙈

🌈 SEE ALSO 🌈

ms_intro(3), mst_init(3), mst_findadjacent(3) and ms_time(3).

like go read those too, bestie, they're the supporting cast and they ate 💖

👑 AUTHOR 👑

Chad Trabant IRIS Data Management Center

okay and that's the whole page!! written by the libmseed API girlies, dated 2013/05/17, and yeah it's the Libmseed API version of MST_ADDMSR(3). stay hydrated, read your manpages, and remember: no checking is done to verify that the record matches the trace in any way 💅✨🦋