MSR_UNPACK(3)

💖 MSR_UNPACK(3) 💖

okay so bestie, we're in the Library Functions Manual rn and this page is literally all about unpacking Mini-SEED records. it's giving "the moment the raw bytes finally reveal their truth" energy and honestly? iconic. 🎀

---

✨ NAME ✨

msr_unpack — Unpacking of Mini-SEED records. that's it, that's the whole vibe. 🦋

---

✨ SYNOPSIS ✨

#include <libmseed.h>

int msr_unpack ( char *record, int reclen, MSRecord **ppmsr,
                 flag dataflag, flag verbose );

int msr_unpack_data ( MSRecord *msr, int swapflag, flag verbose );

two functions, one header, zero drama. let's get into it. 💅

---

✨ DESCRIPTION ✨

so msr_unpack takes a Mini-SEED data record and unpacks it into a MSRecord data structure, and if you want, it'll unpack the actual data samples too. every multi-byte quantity gets byte-swapped into host byte order, no cap. the MSRecord data structure itself is described over in ms_intro(3) if you need the full lore. 📖

the reclen parameter is the length, in bytes, of the data record that record points at.

now here's the part where you gotta pay attention, bestie 👀 — if the *ppmsr pointer is NULL, a brand new MSRecord gets allocated. if it's not NULL, the existing MSRecord gets reinitialized and reused, which means it destroys any previous contents. gone. poof. so be careful with that one fr fr. also the ppmsr pointer itself must not be NULL.

if the dataflag flag is not zero, any data samples in the record get unpacked/decompressed. the supported data encoding formats are: ASCII, INT16, INT32, FLOAT32, FLOAT64, STEIM1 and STEIM2. the MSRecord.datasamples pointer gets set appropriately, and the samples will be either ASCII, 32-bit integers, 32-bit floats or 64-bit floats — with the same byte order as the host machine. MSRecord.numsamples gets set to the actual number of samples unpacked/decompressed. MSRecord.sampletype tells you which kind of sample it is, as one of:

• 'a' — ASCII
• 'i' — 32-bit integers
• 'f' — 32-bit floats
• 'd' — 64-bit doubles

and the size of each sample type in bytes? that's what the get_samplesize(3) lookup routine returns for you. 🍓

the verbose flag controls verbosity — a value of zero means no diagnostic output at all. silence. shhh. 🤫

then we got msr_unpack_data, which unpacks the data samples for an already parsed MSRecord structure, pulling from the original record available at the MSRecord->record pointer. normally msr_unpack calls this itself when dataflag is not zero, but it's genuinely useful when your program needs to unpack the header of a record first and decide later whether it actually needs the samples. main character energy: unpack the header, think about your life, come back for the data. 💅 if you call it independently, the caller must determine if byte swapping of data samples is needed.

---

✨ UNPACKING OVERRIDES ✨

these macros and environment variables affect the unpacking of Mini-SEED. yes, you can override stuff. you're in charge here. 👑

Macros

• MS_UNPACKHEADERBYTEORDER(X)
• MS_UNPACKDATABYTEORDER(X)
• MS_UNPACKDATAFORMAT(X)
• MS_UNPACKDATAFORMATFALLBACK(X)

Environment variables

• UNPACK_HEADER_BYTEORDER
• UNPACK_DATA_BYTEORDER
• UNPACK_DATA_FORMAT
• UNPACK_DATA_FORMAT_FALLBACK

the UNPACK_HEADER_BYTEORDER and UNPACK_DATA_BYTEORDER macros and variables force the byte order of the header and data respectively. they can be set to either 0 (little endian) or 1 (big endian). want the full story on how libmseed figures out a record's byte order? that's in ms_intro(3). 🌈

the UNPACK_DATA_FORMAT macro and variable forces the encoding format, and it should be set to any of the supported format codes — i.e. 10 = Steim-1 compression.

the UNPACK_DATA_FORMAT_FALLBACK macro and variable defines an encoding format used when the SEED data record doesn't indicate the format, i.e. the record does not include a 1000 blockette. by default the fallback encoding format is 10 (Steim-1 compression). if this default gets invoked and the byte order of the data is unspecified, big endian byte order will be assumed. and heads up ⚠️ — if a data record does not include a 1000 blockette, it is not Mini-SEED. the capability to read these records is included only to support legacy data. it's giving "we keep this around for the ancestors". 🙈

---

✨ RETURN VALUE ✨

on the successful parsing of a record, msr_unpack returns MS_NOERROR and populates the MSRecord struct at *ppmsr. 🎉 on error, msr_unpack returns a libmseed error code (defined in libmseed.h). so like, always check your retcode, bestie. periodt.

---

✨ EXAMPLE ✨

skeleton code for unpacking a Mini-SEED record with msr_unpack(3):

main() {
  MSRecord *msr = NULL;
  char *record;
  int reclen;
  int retcode;

  record = recordptr;   /* pointer to Mini-SEED record */
  reclen = 4096;        /* 4096 byte record length */

  /* Unpack record header and data samples */
  retcode = msr_unpack (record, reclen, &msr, 1, verbose);

  if ( retcode != MS_NOERROR )
    fprintf (stderr, "Error parsing record\n");
  else
    printf ("Unpacked %d samples0, msr->numsamples);

  /* Print record information */
  msr_print (msr, verbose);

  msr_free (&msr);
}

look at that little flow — unpack, check, print, free. a whole routine. slay. ✨

---

✨ SEE ALSO ✨

ms_intro(3), msr_pack(3) and msr_print(3). go read those too, iykyk. 🫶

---

✨ AUTHOR ✨

Chad Trabant IRIS Data Management Center

---

and that's the whole page babes 💜 — brought to you by the Libmseed API, dated 2012/12/22, which is technically before some of y'all were born but the code still ate and left no crumbs. go unpack something. 🎀💖✨