Definitions and functions related to individual miniSEED records. More...

Data Structures
struct	MS3Record
	miniSEED record container More...

Functions
int	msr3_parse (const char record, uint64_t recbuflen, MS3Record *ppmsr, uint32_t flags, int8_t verbose)
	Parse miniSEED from a buffer.

int	msr3_pack (const MS3Record msr, void(record_handler)(char , int, void ), void handlerdata, int64_t packedsamples, uint32_t flags, int8_t verbose)
	Pack data into miniSEED records.

int	msr3_repack_mseed3 (const MS3Record msr, char record, uint32_t recbuflen, int8_t verbose)
	Repack a parsed miniSEED record into a version 3 record.

int	msr3_pack_header3 (const MS3Record msr, char record, uint32_t recbuflen, int8_t verbose)
	Pack a miniSEED version 3 header into the specified buffer.

int	msr3_pack_header2 (const MS3Record msr, char record, uint32_t recbuflen, int8_t verbose)
	Pack a miniSEED version 2 header into the specified buffer.

int64_t	msr3_unpack_data (MS3Record *msr, int8_t verbose)
	Unpack data samples for a MS3Record.

int	msr3_data_bounds (const MS3Record msr, uint32_t dataoffset, uint32_t *datasize)
	Determine the data payload bounds for a MS3Record.

int64_t	ms_decode_data (const void input, uint64_t inputsize, uint8_t encoding, uint64_t samplecount, void output, uint64_t outputsize, char sampletype, int8_t swapflag, const char sid, int8_t verbose)
	Decode data samples to a supplied buffer.

MS3Record *	msr3_init (MS3Record *msr)
	Initialize and return an MS3Record.

void	msr3_free (MS3Record **ppmsr)
	Free all memory associated with a MS3Record.

MS3Record *	msr3_duplicate (const MS3Record *msr, int8_t datadup)
	Duplicate a MS3Record.

nstime_t	msr3_endtime (const MS3Record *msr)
	Calculate time of the last sample in a record.

void	msr3_print (const MS3Record *msr, int8_t details)
	Print header values of an MS3Record.

int	msr3_resize_buffer (MS3Record *msr)
	Resize data sample buffer of MS3Record to what is needed.

double	msr3_sampratehz (const MS3Record *msr)
	Calculate sample rate in samples/second (Hertz) for a given MS3Record.

nstime_t	msr3_nsperiod (const MS3Record *msr)
	Calculate sample period in nanoseconds/sample for a given MS3Record.

double	msr3_host_latency (const MS3Record *msr)
	Calculate data latency based on the host time.

int64_t	ms3_detect (const char record, uint64_t recbuflen, uint8_t formatversion)
	Detect miniSEED record in buffer.

int	ms_parse_raw3 (const char *record, int maxreclen, int8_t details)
	Parse and verify a miniSEED 3.x record header.

int	ms_parse_raw2 (const char *record, int maxreclen, int8_t details, int8_t swapflag)
	Parse and verify a miniSEED 2.x record header.

Detailed Description

Definitions and functions related to individual miniSEED records.

Data Structure Documentation

◆ MS3Record

struct MS3Record

miniSEED record container

Data Fields
const char *	record	Raw miniSEED record, if available.
int32_t	reclen	Length of miniSEED record in bytes.
uint8_t	swapflag	Byte swap indicator (bitmask), see Byte swap flags.
char	sid[LM_SIDLEN]	Source identifier as URN, max length LM_SIDLEN.
uint8_t	formatversion	Format major version.
uint8_t	flags	Record-level bit flags.
nstime_t	starttime	Record start time (first sample)
double	samprate	Nominal sample rate as samples/second (Hz) or period (s)
int16_t	encoding	Data encoding format, see Data Encodings.
uint8_t	pubversion	Publication version.
int64_t	samplecnt	Number of samples in record.
uint32_t	crc	CRC of entire record.
uint16_t	extralength	Length of extra headers in bytes.
uint32_t	datalength	Length of data payload in bytes.
char *	extra	Pointer to extra headers.
void *	datasamples	Data samples, numsamples of type sampletype.
uint64_t	datasize	Size of datasamples buffer in bytes.
int64_t	numsamples	Number of data samples in datasamples.
char	sampletype	Sample type code: t, i, f, d Sample Types.

Function Documentation

◆ msr3_parse()

int msr3_parse	(	const char *	record,
		uint64_t	recbuflen,
		MS3Record **	ppmsr,
		uint32_t	flags,
		int8_t	verbose )

extern

Parse miniSEED from a buffer.

This routine will attempt to parse (detect and unpack) a miniSEED record from a specified memory buffer and populate a supplied MS3Record structure. Both miniSEED 2.x and 3.x records are supported.

The record length is automatically detected. For miniSEED 2.x this means the record must contain a 1000 blockette.

Parameters

record	Buffer containing record to parse
recbuflen	Buffer length in bytes
ppmsr	Pointer-to-point to a MS3Record that will be populated
flags	Flags controlling features: `MSF_UNPACKDATA` - Unpack data samples `MSF_VALIDATECRC` Validate CRC (if present in format)
verbose	control verbosity of diagnostic output

Returns: Parsing status

Return values

0	Success, populates the supplied MS3Record.
>0	Data record detected but not enough data is present, the return value is a hint of how many more bytes are needed.
<0	library error code is returned.

MessageOnError - this function logs a message on error except MS_NOTSEED

◆ msr3_pack()

int msr3_pack	(	const MS3Record *	msr,
		void(*	record_handler )(char , int, void ),
		void *	handlerdata,
		int64_t *	packedsamples,
		uint32_t	flags,
		int8_t	verbose )

extern

Pack data into miniSEED records.

Packing is performed according to the version at MS3Record::formatversion.

The MS3Record::datasamples array and MS3Record::numsamples value will not be changed by this routine. It is the responsibility of the calling routine to adjust the data buffer if desired.

As each record is filled and finished they are passed to record_handler() which should expect 1) a char* to the record, 2) the length of the record and 3) a pointer supplied by the original caller containing optional private data (handlerdata). It is the responsibility of record_handler() to process the record, the memory will be re-used or freed when record_handler() returns.

The following data encodings and expected MS3Record::sampletype are supported:

DE_TEXT (0), Text, expects type 't'
DE_INT16 (1), 16-bit integer, expects type 'i'
DE_INT32 (3), 32-bit integer, expects type 'i'
DE_FLOAT32 (4), 32-bit float (IEEE), expects type 'f'
DE_FLOAT64 (5), 64-bit float (IEEE), expects type 'd'
DE_STEIM1 (10), Stiem-1 compressed integers, expects type 'i'
DE_STEIM2 (11), Stiem-2 compressed integers, expects type 'i'

If flags has MSF_FLUSHDATA set, all of the data will be packed into data records even though the last one will probably be smaller than requested or, in the case of miniSEED 2, unfilled.

Default values are: record length = 4096, encoding = 11 (Steim2). The defaults are triggered when msr.reclen and msr.encoding are set to -1.

Parameters

[in]	msr	MS3Record containing data to pack
[in]	record_handler()	Callback function called for each record
[in]	handlerdata	A pointer that will be provided to the record_handler()
[out]	packedsamples	The number of samples packed, returned to caller
[in]	flags	Bit flags used to control the packing process: `MSF_FLUSHDATA` : Pack all data in the buffer `MSF_PACKVER2` : Pack miniSEED version 2 regardless of MS3Record.formatversion
[in]	verbose	Controls logging verbosity, 0 is no diagnostic output

Returns: the number of records created on success and -1 on error.

MessageOnError - this function logs a message on error

◆ msr3_repack_mseed3()

int msr3_repack_mseed3	(	const MS3Record *	msr,
		char *	record,
		uint32_t	recbuflen,
		int8_t	verbose )

extern

Repack a parsed miniSEED record into a version 3 record.

Pack the parsed header into a version 3 header and copy the raw encoded data from the original record. The original record must be available at the MS3Record.record pointer.

This can be used to efficiently convert format versions or modify header values without unpacking the data samples.

Parameters

[in]	msr	MS3Record containing record to repack
[out]	record	Destination buffer for repacked record
[in]	recbuflen	Length of destination buffer
[in]	verbose	Controls logging verbosity, 0 is no diagnostic output

Returns: record length on success and -1 on error.

MessageOnError - this function logs a message on error

◆ msr3_pack_header3()

int msr3_pack_header3	(	const MS3Record *	msr,
		char *	record,
		uint32_t	recbuflen,
		int8_t	verbose )

extern

Pack a miniSEED version 3 header into the specified buffer.

Default values are: record length = 4096, encoding = 11 (Steim2). The defaults are triggered when msr.reclen and msr.encoding are set to -1.

Parameters

[in]	msr	MS3Record to pack
[out]	record	Destination for packed header
[in]	recbuflen	Length of destination buffer
[in]	verbose	Controls logging verbosity, 0 is no diagnostic output

Returns: the size of the header (fixed and extra) on success, otherwise -1.

MessageOnError - this function logs a message on error

◆ msr3_pack_header2()

int msr3_pack_header2	(	const MS3Record *	msr,
		char *	record,
		uint32_t	recbuflen,
		int8_t	verbose )

extern

Pack a miniSEED version 2 header into the specified buffer.

Default values are: record length = 4096, encoding = 11 (Steim2). The defaults are triggered when msr.reclen and msr.encoding are set to -1.

Parameters

[in]	msr	MS3Record to pack
[out]	record	Destination for packed header
[in]	recbuflen	Length of destination buffer
[in]	verbose	Controls logging verbosity, 0 is no diagnostic output

Returns: the size of the header (fixed and blockettes) on success, otherwise -1.

MessageOnError - this function logs a message on error

◆ msr3_unpack_data()

int64_t msr3_unpack_data	(	MS3Record *	msr,
		int8_t	verbose )

extern

Unpack data samples for a MS3Record.

This routine can be used to unpack the data samples for a MS3Record that was earlier parsed without the data samples being decoded.

The packed/encoded data is accessed in the record indicated by MS3Record.record and the unpacked samples are placed in MS3Record.datasamples. The resulting data samples are either text characters, 32-bit integers, 32-bit floats or 64-bit floats in host byte order.

An internal buffer is allocated if the encoded data is not aligned for the sample size, which is a decent indicator of the alignment needed for decoding efficiently.

Parameters

[in]	msr	Target MS3Record to unpack data samples
[in]	verbose	Flag to control verbosity, 0 means no diagnostic output

Returns: number of samples unpacked or negative libmseed error code.

MessageOnError - this function logs a message on error

◆ msr3_data_bounds()

int msr3_data_bounds	(	const MS3Record *	msr,
		uint32_t *	dataoffset,
		uint32_t *	datasize )

extern

Determine the data payload bounds for a MS3Record.

Bounds are the starting offset in record and size. For miniSEED 2.x the raw record is expected to be located at the MS3Record.record pointer.

When the encoding is a fixed length per sample (text, integers, or floats), calculate the data size based on the sample count and use if less than size determined otherwise.

When the encoding is Steim1 or Steim2, search for 64-byte padding frames (all zeros) at the end of the payload and remove from the reported size.

Parameters

[in]	msr	The MS3Record to determine payload bounds for
[out]	dataoffset	Offset from start of record to start of payload
[out]	datasize	Payload size in bytes

Returns: 0 on success or negative library error code.

MessageOnError - this function logs a message on error

◆ ms_decode_data()

int64_t ms_decode_data	(	const void *	input,
		uint64_t	inputsize,
		uint8_t	encoding,
		uint64_t	samplecount,
		void *	output,
		uint64_t	outputsize,
		char *	sampletype,
		int8_t	swapflag,
		const char *	sid,
		int8_t	verbose )

extern

Decode data samples to a supplied buffer.

Parameters

[in]	input	Encoded data
[in]	inputsize	Size of input buffer in bytes
[in]	encoding	Data encoding
[in]	samplecount	Number of samples to decode
[out]	output	Decoded data
[in]	outputsize	Size of output buffer in bytes
[out]	sampletype	Pointer to (single character) sample type of decoded data
[in]	swapflag	Flag indicating if encoded data needs swapping
[in]	sid	Source identifier to include in diagnostic/error messages
[in]	verbose	Flag to control verbosity, 0 means no diagnostic output

Returns: number of samples decoded or negative libmseed error code.

MessageOnError - this function logs a message on error

◆ msr3_init()

MS3Record * msr3_init ( MS3Record * msr )

extern

Initialize and return an MS3Record.

Memory is allocated if for a new MS3Record if msr is NULL.

If memory for the datasamples field has been allocated the pointer will be retained for reuse. If memory for extra headers has been allocated it will be released.

Parameters

[in] msr A MS3Record to re-initialize

Returns: a pointer to a MS3Record struct on success or NULL on error.

MessageOnError - this function logs a message on error

◆ msr3_free()

void msr3_free ( MS3Record ** ppmsr )

extern

Free all memory associated with a MS3Record.

Free all memory associated with a MS3Record, including extra header and data samples if present.

Parameters

[in] ppmsr Pointer to point of the MS3Record to free

◆ msr3_duplicate()

MS3Record * msr3_duplicate	(	const MS3Record *	msr,
		int8_t	datadup )

extern

Duplicate a MS3Record.

Extra headers are duplicated as well.

If the datadup flag is true (non-zero) and the source MS3Record has associated data samples copy them as well.

Parameters

[in]	msr	MS3Record to duplicate
[in]	datadup	Flag to control duplication of data samples

Returns: Pointer to a new MS3Record on success and NULL on error

MessageOnError - this function logs a message on error

◆ msr3_endtime()

nstime_t msr3_endtime ( const MS3Record * msr )

extern

Calculate time of the last sample in a record.

If leap seconds have been loaded into the internal library list: when a record completely contains a leap second, starts before and ends after, the calculated end time will be adjusted (reduced) by one second.

Note: On the epoch time scale the value of a leap second is the same as the second following the leap second, without external information the values are ambiguous.

See also: ms_readleapsecondfile()

Parameters

[in] msr MS3Record to calculate end time of

Returns: Time of the last sample on success and NSTERROR on error.

◆ msr3_print()

void msr3_print	(	const MS3Record *	msr,
		int8_t	details )

extern

Print header values of an MS3Record.

Parameters

[in]	msr	MS3Record to print
[in]	details	Flags to control the level of details: `0` - print a single summary line `1` - print most details of header `>1` - print all details of header and extra headers if present

◆ msr3_resize_buffer()

int msr3_resize_buffer ( MS3Record * msr )

extern

Resize data sample buffer of MS3Record to what is needed.

This routine should only be used if pre-allocation of memory, via libmseed_prealloc_block_size, was enabled to allocate the buffer.

Parameters

[in] msr MS3Record to resize buffer

Returns: Return 0 on success, otherwise returns a libmseed error code.

MessageOnError - this function logs a message on error

◆ msr3_sampratehz()

double msr3_sampratehz ( const MS3Record * msr )

externinline

Calculate sample rate in samples/second (Hertz) for a given MS3Record.

Parameters

[in] msr MS3Record to calculate sample rate for

Returns: Return sample rate in Hertz (samples per second)

◆ msr3_nsperiod()

nstime_t msr3_nsperiod ( const MS3Record * msr )

externinline

Calculate sample period in nanoseconds/sample for a given MS3Record.

Parameters

[in] msr MS3Record to calculate sample period for

Returns: Return sample period in nanoseconds (nanoseconds per sample)

◆ msr3_host_latency()

double msr3_host_latency ( const MS3Record * msr )

extern

Calculate data latency based on the host time.

Calculation is based on the time of the last sample in the record; in other words, the difference between the host time and the time of the last sample in the record.

Double precision is returned, but the true precision is dependent on the accuracy of the host system clock among other things.

Parameters

[in] msr MS3Record to calculate latency for

Returns: seconds of latency or 0.0 on error (indistinguishable from 0.0 latency).

◆ ms3_detect()

int64_t ms3_detect	(	const char *	record,
		uint64_t	recbuflen,
		uint8_t *	formatversion )

extern

Detect miniSEED record in buffer.

Determine if the buffer contains a miniSEED data record by verifying known signatures (fields with known limited values).

If miniSEED 2.x is detected, search the record up to recbuflen bytes for a 1000 blockette. If no blockette 1000 is found, search at 64-byte offsets for the fixed section of the next header, thereby implying the record length.

Parameters

[in]	record	Buffer to test for record
[in]	recbuflen	Length of buffer
[out]	formatversion	Major version of format detected, 0 if unknown

Return values

-1	Data record not detected or error
0	Data record detected but could not determine length
>0	Size of the record in bytes

MessageOnError - this function logs a message on error

◆ ms_parse_raw3()

int ms_parse_raw3	(	const char *	record,
		int	maxreclen,
		int8_t	details )

extern

Parse and verify a miniSEED 3.x record header.

Parsing is done at the lowest level, printing error messages for invalid header values and optionally print raw header values.

The buffer at record is assumed to be a miniSEED record. Not every possible test is performed, common errors and those causing library parsing to fail should be detected.

This routine is primarily intended to diagnose invalid miniSEED headers.

Parameters

[in]	record	Buffer to parse as miniSEED
[in]	maxreclen	Maximum length to search in buffer
[in]	details	Controls diagnostic output as follows: `0` - only print error messages for invalid header fields `1` - print basic fields in addition to invalid field errors `2` - print all fields in addition to invalid field errors

Returns: 0 when no errors were detected or a positive count of errors detected.

MessageOnError - this function logs a message on error

◆ ms_parse_raw2()

int ms_parse_raw2	(	const char *	record,
		int	maxreclen,
		int8_t	details,
		int8_t	swapflag )

extern

Parse and verify a miniSEED 2.x record header.

Parsing is done at the lowest level, printing error messages for invalid header values and optionally print raw header values.

The buffer record is assumed to be a miniSEED record. Not every possible test is performed, common errors and those causing libmseed parsing to fail should be detected.

This routine is primarily intended to diagnose invalid miniSEED headers.

Parameters

[in]	record	Buffer to parse as miniSEED
[in]	maxreclen	Maximum length to search in buffer
[in]	details	Controls diagnostic output as follows: `0` - only print error messages for invalid header fields `1` - print basic fields in addition to invalid field errors `2` - print all fields in addition to invalid field errors
[in]	swapflag	Flag controlling byte-swapping as follows: `1` - swap multibyte quantities `0` - do not swap `-1` - autodetect byte order using year test, swap if needed

Returns: 0 when no errors were detected or a positive count of errors detected.

MessageOnError - this function logs a message on error

Data Structures

Functions

Detailed Description

Data Structure Documentation

◆ MS3Record

Function Documentation

◆ msr3_parse()

◆ msr3_pack()

◆ msr3_repack_mseed3()

◆ msr3_pack_header3()

◆ msr3_pack_header2()

◆ msr3_unpack_data()

◆ msr3_data_bounds()

◆ ms_decode_data()

◆ msr3_init()

◆ msr3_free()

◆ msr3_duplicate()

◆ msr3_endtime()

◆ msr3_print()

◆ msr3_resize_buffer()

◆ msr3_sampratehz()

◆ msr3_nsperiod()

◆ msr3_host_latency()

◆ ms3_detect()

◆ ms_parse_raw3()

◆ ms_parse_raw2()