MSR_PARSE(3)

💖 MSR_PARSE 💖

okay bestie, welcome to the msr_parse page — part of the Library Functions Manual, section 3, she's a library call, she's iconic, she's literally the one who detects and parses a SEED data record from a memory buffer. let's get into it 🫶

---

✨ NAME ✨

msr_parse — detect and parse a SEED data record from a memory buffer

---

🌸 SYNOPSIS 🌸

#include <libmseed.h>

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

int  msr_parse_selection ( char *recbuf, int recbuflen,
                           int64_t *offset, MSRecord **ppmsr,
                           int reclen, Selections *selections,
                           flag dataflag, flag verbose );

int  ms_detect ( const char *record, int recbuflen );

---

🦋 DESCRIPTION 🦋

so msr_parse parses a SEED data record out of the record buffer and populates the MSRecord structure sitting at ppmsr, allocating one if it needs to. the recbuflen argument is the length of that record buffer. and listen — records must begin at the start of the buffer. no exceptions, no vibes-based offsets. 💅

if reclen is 0 or negative, the length of record gets automatically determined. otherwise reclen should be the correct record length. for auto detection of record length, the record should include a 1000 blockette or be followed by another record header in the buffer. (iykyk 🎀)

if dataflag is true (non-zero), the data samples get unpacked while parsing the record. this argument is passed directly to msr_unpack(3).

msr_parse_selection parses the first SEED data record from the recbuf buffer that matches the optional selections. the offset value tells it where to start searching the buffer. on success, the MSRecord structure at ppmsr is populated and the offset to the record in the buffer gets set. see the example below for the intended usage pattern — it's giving "read this before you yolo it" ✨

ms_detect determines whether the supplied record buffer contains a SEED data record by verifying known signatures. if a record is found, the record length is determined by:

1. Searching the buffer up to recbuflen for a Blockette 1000.
2. If no Blockette 1000 is found, search at MINRECLEN-byte offsets for the fixed section of the next header in the buffer, thereby implying the record length.

---

💜 RETURN VALUES 💜

msr_parse returns values:

• 0 — on success, and populates the supplied MSRecord. slay 💖
• >0 — data record was detected but not enough data is present in buffer. the value returned is a hint of how much more data is needed. (she's telling you to feed her more 🍓)
• <0 — on error, a negative libmseed error value is returned. 💀

ms_detect returns values:

• -1 — data record not detected or error
• 0 — data record detected but could not determine length
• >0 — length of the data record in bytes

---

🌈 EXAMPLE USAGE OF MS_PARSE_SELECTION() 🌈

The ms_parse_selection() routine uses the initial setting of offset as the starting point to search the buffer. On successful parsing of a miniSEED record the value of offset will be the offset in the buffer to the record parsed.

To properly parse all records matching specificed selection criteria, a caller must check and manage the value of offset. In particular, when the end of the buffer is reached a value of MS_GENERROR will be returned and the caller should check if the offset is still within the buffer length to determine if this is a parsing error or simply the end of the buffer.

The following example illustrates the intended usage:

char *recbuf = <memory buffer containing records>;
int64_t recbuflen = <length of buffer>;
int64_t offset = 0;
MSRecord *msr = NULL;
int reclen = -1;
Selections *selections = NULL;
flag dataflag = 1;
flag verbose = 0;

// You probaby want to set Selections
// For example with a call to ms_readselectionsfile (&selections, selectfile)

/* Loop over all selected records in recbuf */
while ( offset < recbuflen )
  {
    if ( msr_parse_selection (recbuf, recbuflen, &offset, &msr, reclen, selections, dataflag, verbose) )
      {
        /* Only print error if offset is still within buffer length */
        if ( verbose && offset < recbuflen )
        ms_log (2, "Error parsing record at offset %"PRId64"0, offset);
      }
    else /* Successfully found and parsed record */
      {
        /* Do something with the record, for example print the details */
        msr_print (msr, verbose);

        /* Increment offset in buffer for subsequent call to msr_parse_selection() */
        offset += msr->reclen;
      }
  }

/* Clean up */
msr_free (&msr);

if ( selections )
  ms_freeselections (selections);

real talk: manage that offset yourself, bestie. the routine is not gonna do it for you and that's on periodt. 👑

---

👑 SEE ALSO 👑

msr_unpack(3), ms_parse_raw(3) and ms_errorstr(3)

---

💅 AUTHOR 💅

Chad Trabant IRIS Data Management Center

---

and that's the whole page, bestie!! 🎀 this was the Libmseed API edition, dated 2013/01/07 — literally vintage, literally iconic, and honestly? she ate. go parse some records, you've got this 💖✨🦋