sac

sac file I/O and manipulation More...

Enumerations
enum	sac::CutAction
	Sac Cutting Behavior.
enum	HeaderID {   SAC_DELTA = 1, SAC_DEPMIN = 2, SAC_DEPMAX = 3, SAC_SCALE = 4,   SAC_ODELTA = 5, SAC_B = 6, SAC_E = 7, SAC_O = 8,   SAC_A = 9, SAC_FMT = 10, SAC_T0 = 11, SAC_T1 = 12,   SAC_T2 = 13, SAC_T3 = 14, SAC_T4 = 15, SAC_T5 = 16,   SAC_T6 = 17, SAC_T7 = 18, SAC_T8 = 19, SAC_T9 = 20,   SAC_F = 21, SAC_RESP0 = 22, SAC_RESP1 = 23, SAC_RESP2 = 24,   SAC_RESP3 = 25, SAC_RESP4 = 26, SAC_RESP5 = 27, SAC_RESP6 = 28,   SAC_RESP7 = 29, SAC_RESP8 = 30, SAC_RESP9 = 31, SAC_STLA = 32,   SAC_STLO = 33, SAC_STEL = 34, SAC_STDP = 35, SAC_EVLA = 36,   SAC_EVLO = 37, SAC_EVEL = 38, SAC_EVDP = 39, SAC_MAG = 40,   SAC_USER0 = 41, SAC_USER1 = 42, SAC_USER2 = 43, SAC_USER3 = 44,   SAC_USER4 = 45, SAC_USER5 = 46, SAC_USER6 = 47, SAC_USER7 = 48,   SAC_USER8 = 49, SAC_USER9 = 50, SAC_DIST = 51, SAC_AZ = 52,   SAC_BAZ = 53, SAC_GCARC = 54, SAC_SB = 55, SAC_SDELTA = 56,   SAC_DEPMEN = 57, SAC_CMPAZ = 58, SAC_CMPINC = 59, SAC_XMIN = 60,   SAC_XMAX = 61, SAC_YMIN = 62, SAC_YMAX = 63 , SAC_YEAR = 71,   SAC_DAY = 72, SAC_HOUR = 73, SAC_MIN = 74, SAC_SEC = 75,   SAC_MSEC = 76, SAC_HDR = 77, SAC_ORID = 78, SAC_EVID = 79,   SAC_NPTS = 80, SAC_NSNPTS = 81, SAC_WFID = 82, SAC_NX = 83,   SAC_NY = 84 , SAC_FILE_TYPE = 86, SAC_DEP_TYPE = 87, SAC_ZERO_TIME = 88 ,   SAC_INST_TYPE = 90, SAC_STREG = 91, SAC_EVREG = 92, SAC_EVENT_TYPE = 93,   SAC_QUAL = 94, SAC_SYNTH = 95, SAC_MAG_TYPE = 96, SAC_MAG_SRC = 97 ,   SAC_EVEN = 106, SAC_POLARITY = 107, SAC_OVERWRITE = 108, SAC_CALC_DIST_AZ = 109 ,   SAC_STA = 111, SAC_EVENT = 112 , SAC_HOLE = 114, SAC_KO = 115,   SAC_KA = 116, SAC_KT0 = 117, SAC_KT1 = 118, SAC_KT2 = 119,   SAC_KT3 = 120, SAC_KT4 = 121, SAC_KT5 = 122, SAC_KT6 = 123,   SAC_KT7 = 124, SAC_KT8 = 125, SAC_KT9 = 126, SAC_KF = 127,   SAC_KUSER0 = 128, SAC_KUSER1 = 129, SAC_KUSER2 = 130, SAC_CHA = 131,   SAC_NET = 132, SAC_DATRD = 133, SAC_INST = 134, SAC_DATE = 135,   SAC_TIME = 136, SAC_STCMP = 137, SAC_FILENAME = 138, SAC_AMARKER = 140,   SAC_OMARKER = 141, SAC_FMARKER = 142, SAC_T0MARKER = 143, SAC_T1MARKER = 144,   SAC_T2MARKER = 145, SAC_T3MARKER = 146, SAC_T4MARKER = 147, SAC_T5MARKER = 148,   SAC_T6MARKER = 149, SAC_T7MARKER = 150, SAC_T8MARKER = 151, SAC_T9MARKER = 152,   SAC_MONTH = 153, SAC_MONTH_DAY = 154, SAC_DATE_TIME = 155 }
	Sac Header IDs. More...

Functions
sac *	sac::sac_read (char *filename, int *nerr)
	Read a sac file. More...
sac *	sac::sac_read_header (char *filename, int *nerr)
	Read a sac file header. More...
void	sac::sac_write (sac *s, char *filename, int *nerr)
	write a sac file to disk More...
void	sac::sac_write_header (sac *s, char *filename, int *nerr)
	write a sac header to disk More...
int	sac::sac_is_timeval (int hid)
	Identify if a header is a time value. More...
int	sac::sac_set_pick (sac *s, int n, double value)
	Set a time pick value. More...
int	sac::sac_get_pick (sac *s, int n, double *t)
	Get a timing pick. More...
void	sac::sac_set_v7 (sac *s)
	Set the header version to 7. More...
void	sac::sac_set_v6 (sac *s)
	Set the header version to 6. More...
sac *	sac::sac_new ()
	create a new sac file structure More...
void	sac::sac_free (sac *s)
	free a sac file structure More...
void	sac::sac_alloc (sac *s)
	allocate the sac data portion of a sac strucutre More...
void	sac::sac_be (sac *s)
	Set the beginning and end time for a sac file. More...
void	sac::sac_header_copy (sac *to, sac *from)
	copy the sac header More...
void	sac::sac_meta_copy (sac *to, sac *from)
	copy the sac meta header More...
void	sac::sac_data_copy (sac *to, sac *from)
	copy sac data More...
sac *	sac::sac_copy (sac *s)
	copy a sac file More...
off_t	sac::sac_size (sac *s)
	Get the size of a sac file in bytes. More...
int	sac::sac_comps (sac *s)
	Get the number of data components. More...
void	sac::sac_extrema (sac *s)
	compute depmin, depmax, and depmen in sac header More...
int	sac::sac_time_to_index (sac *s, double t)
	Convert a time to index. More...
sac *	sac::sac_read_with_cut (char *filename, char *c1, double t1, char *c2, double t2, enum CutAction cutact, int *nerr)
	read a sac file while cutting More...
int	sac::sac_set_string (sac *s, int hdr, char *v)
	Set a character string in a sac file. More...
int	sac::sac_get_string (sac *s, int hdr, char *v, size_t n)
	Get a character string from a sac file. More...
int	sac::sac_set_float (sac *s, int hdr, double v)
	Set a floating point value in a sac file. More...
int	sac::sac_get_float (sac *s, int hdr, double *v)
	Get a floating point value from a sac file. More...
int	sac::sac_set_int (sac *s, int hdr, int v)
	Set a integer value in a sac file. More...
int	sac::sac_get_int (sac *s, int hdr, int *v)
	Get a integer value from a sac file. More...
int	sac::sac_hdr_defined (sac *s,...)
	Check if multiple header values are defined. More...
int	sac::sac_get_time_ref (sac *s, timespec64 *t)
	Get the reference time from a sac file. More...
int	sac::sac_get_time (sac *s, int hdr, timespec64 *t)
	Get time value from sac file. More...
int	sac::sac_set_time (sac *s, timespec64 t)
int	sac::sac_fmt (char *dst, size_t n, const char *fmt, sac *s)
	format sac values into a string More...

Detailed Description

sac file I/O and manipulation

Enumeration Type Documentation

HeaderID

enum HeaderID

Sac Header IDs.

Enumerator
SAC_DELTA	delta
SAC_DEPMIN	depmin
SAC_DEPMAX	depmax
SAC_SCALE	scale
SAC_ODELTA	odelta
SAC_B	b
SAC_E	e
SAC_O	o
SAC_A	a
SAC_FMT	fmt
SAC_T0	t0
SAC_T1	t1
SAC_T2	t2
SAC_T3	t3
SAC_T4	t4
SAC_T5	t5
SAC_T6	t6
SAC_T7	t7
SAC_T8	t8
SAC_T9	t9
SAC_F	f
SAC_RESP0	resp0
SAC_RESP1	resp1
SAC_RESP2	resp2
SAC_RESP3	resp3
SAC_RESP4	resp4
SAC_RESP5	resp5
SAC_RESP6	resp6
SAC_RESP7	resp7
SAC_RESP8	resp8
SAC_RESP9	resp9
SAC_STLA	stla
SAC_STLO	stlo
SAC_STEL	stel
SAC_STDP	stdp
SAC_EVLA	evla
SAC_EVLO	evlo
SAC_EVEL	evel
SAC_EVDP	evdp
SAC_MAG	mag
SAC_USER0	user0
SAC_USER1	user1
SAC_USER2	user2
SAC_USER3	user3
SAC_USER4	user4
SAC_USER5	user5
SAC_USER6	user6
SAC_USER7	user7
SAC_USER8	user8
SAC_USER9	user9
SAC_DIST	dist
SAC_AZ	az
SAC_BAZ	baz
SAC_GCARC	gcarc
SAC_SB	sb
SAC_SDELTA	sdelta
SAC_DEPMEN	depmen
SAC_CMPAZ	cmpaz
SAC_CMPINC	cmpinc
SAC_XMIN	xmin
SAC_XMAX	xmax
SAC_YMIN	ymin
SAC_YMAX	ymax
SAC_YEAR	year
SAC_DAY	day of the year
SAC_HOUR	hour
SAC_MIN	min
SAC_SEC	sec
SAC_MSEC	millisecond
SAC_HDR	header version
SAC_ORID	origin id
SAC_EVID	event id
SAC_NPTS	npts
SAC_NSNPTS	nsnpts
SAC_WFID	waveform id
SAC_NX	nx
SAC_NY	ny
SAC_FILE_TYPE	file type, iftype
SAC_DEP_TYPE	dependent variable type, idep
SAC_ZERO_TIME	zero time equivalent, iztype
SAC_INST_TYPE	instrument type, iinst
SAC_STREG	station region
SAC_EVREG	event region
SAC_EVENT_TYPE	event type
SAC_QUAL	quality
SAC_SYNTH	synthetic flag
SAC_MAG_TYPE	magnitude type
SAC_MAG_SRC	magnitide src
SAC_EVEN	evenly spaced, leven
SAC_POLARITY	polarity, lpspol
SAC_OVERWRITE	overwrite, lovrok
SAC_CALC_DIST_AZ	calculate distance and azimuth, lcalda
SAC_STA	station
SAC_EVENT	event
SAC_HOLE	hole or location
SAC_KO	ko
SAC_KA	ka
SAC_KT0	kt0
SAC_KT1	kt1
SAC_KT2	kt2
SAC_KT3	kt3
SAC_KT4	kt4
SAC_KT5	kt5
SAC_KT6	kt6
SAC_KT7	kt7
SAC_KT8	kt8
SAC_KT9	kt9
SAC_KF	kf
SAC_KUSER0	kuser0
SAC_KUSER1	kuser1
SAC_KUSER2	kuser2
SAC_CHA	channel
SAC_NET	newtowrk
SAC_DATRD	date data read
SAC_INST	instrument
SAC_DATE	kzdate
SAC_TIME	kztime
SAC_STCMP	station component
SAC_FILENAME	filename
SAC_AMARKER	amarker
SAC_OMARKER	omarker
SAC_FMARKER	fmarker
SAC_T0MARKER	t0marker
SAC_T1MARKER	t1marker
SAC_T2MARKER	t2marker
SAC_T3MARKER	t3marker
SAC_T4MARKER	t4marker
SAC_T5MARKER	t5marker
SAC_T6MARKER	t6marker
SAC_T7MARKER	t7marker
SAC_T8MARKER	t8marker
SAC_T9MARKER	t9marker
SAC_MONTH	month
SAC_MONTH_DAY	day of the month
SAC_DATE_TIME	full date time references

Function Documentation

sac_alloc()

void sac_alloc

(

sac *

s

)

allocate the sac data portion of a sac strucutre

allocate the sac data poriton of a sac structure. The memory size the data and components are determined by sac_comps() and the number of points npts. Any previous data is freed before allocation

Parameters

s	sac file to allocate the data for

Example of creating and allocating space for data in a sac file in memory

sac *s = sac_new();
sac_set_int(s, SAC_NPTS, 100);
sac_alloc(s);
assert_ne(s->y, NULL);
assert_eq(s->x, NULL);

// Set the file type to Amplitude/Phase (2 components)
sac_set_int(s, SAC_FILE_TYPE, IAMPH);
sac_alloc(s);
assert_ne(s->y, NULL);
assert_ne(s->x, NULL);

sac_be()

void sac_be

(

sac *

s

)

Set the beginning and end time for a sac file.

Set the beginning and end time for a sac file

Parameters

s

sac file

double e = 0.0;
sac *s = sac_new();
sac_set_int(s, SAC_NPTS, 100);
sac_set_float(s, SAC_DELTA, 1.0);
sac_set_float(s, SAC_B, 0.0);
sac_be(s);
sac_get_float(s, SAC_E, &e);
assert_eq(e, 99.0);

sac_comps()

int sac_comps

(

sac *

s

)

Get the number of data components.

Get the number of data components: 1 - Evenly spaced time (ITIME), general xy (IXY) or unknown (IUKN), xyz (IXYZ) 2 - Unevenly spcaed time (ITIME), real-imag (IRLIM), amp-phase (IAMPH)

Parameters

s

sac file

Returns

Number of data components

int n = 0;
sac *s = sac_new();
n = sac_comps(s);
assert_eq(n, 1);

// Unevenly spaced time series file
sac_set_int(s, SAC_EVEN, 0);
n = sac_comps(s);
assert_eq(n, 2);

// Evenly spaced xy file
sac_set_int(s, SAC_EVEN, 1);
sac_set_int(s, SAC_FILE_TYPE, IXY);
n = sac_comps(s);
assert_eq(n, 1);

// Unevenly spaced xy file
sac_set_int(s, SAC_EVEN, 0);
sac_set_int(s, SAC_FILE_TYPE, IXY);
n = sac_comps(s);
assert_eq(n, 2);

// Real - Imaginary data file
sac_set_int(s, SAC_FILE_TYPE, IRLIM);
n = sac_comps(s);
assert_eq(n, 2);

// Amplitude - Phase data file
sac_set_int(s, SAC_FILE_TYPE, IAMPH);
n = sac_comps(s);
assert_eq(n, 2);

sac_copy()

sac * sac_copy

(

sac *

s

)

copy a sac file

copy a sac file: header, meta, and data. This is probably what is usually wanted. This creates a new sac file, copieds the header, meta data, and the actual data.

Parameters

s	sac file to copy

Returns

copy of sac file

sac *new = NULL;
int n_old = 0, n_new = 0;
int nerr = 0;

// Read in an existing file
sac *old = sac_read("t/test_io_small.sac", &nerr);
assert_eq(nerr, 0);
assert_ne(old->y, NULL);

// Create a new sac file
new = sac_copy(old);
assert_ne(new->y, NULL);

// Check the number of points
sac_get_int(old, SAC_NPTS, &n_old);
sac_get_int(new, SAC_NPTS, &n_new);
assert_eq(n_old, n_new);

sac_data_copy()

void sac_data_copy	(	sac *	to,
		sac *	from
	)

copy sac data

copy sac data from one file to another. For data to be successfully copied, the following fields must match:

• SAC_NPTS
• SAC_FILE_TYPE
• SAC_EVEN

Parameters

to	destination
from	source

Returns

return type

sac *new = NULL;
int nerr = 0;

// Read in an existing file
sac *old = sac_read("t/test_io_small.sac", &nerr);
assert_eq(nerr, 0);
assert_ne(old->y, NULL);

// Create a new sac file
new = sac_new();
assert_eq(new->y, NULL);

// Copy header from old file to new file
sac_header_copy(new, old);

// Copy header from old file to new fiel
sac_data_copy(new, old);

assert_ne(new->y, NULL);

sac_extrema()

void sac_extrema

(

sac *

s

)

compute depmin, depmax, and depmen in sac header

compute depmin, depmax and depmen value for the sac header report if any of the values are not finite numbers, i.e. inf or nan

Parameters

s

sac file

Note

This sets the following sac header values:

• depmin
• depmax
• depmen

Example of

int i = 0;
double v = 0.0;
sac *s = sac_new();

// Define a data series, line from 0 to 99
sac_set_int(s, SAC_NPTS, 100);
sac_alloc(s);
for(i = 0; i < 100; i++) {
   s->y[i] = (float) i;
}

// Determine min, max and mean of data
sac_extrema(s);

// Get min, max and mean
sac_get_float(s, SAC_DEPMIN, &v);
assert_eq(v, 0.0);
sac_get_float(s, SAC_DEPMAX, &v);
assert_eq(v, 99.0);
sac_get_float(s, SAC_DEPMEN, &v);
assert_eq(v, 49.5);

sac_fmt()

int sac_fmt	(	char *	dst,
		size_t	n,
		const char *	fmt,
		sac *	s
	)

format sac values into a string

format sac values into a string

• %% Output the '' character
• %E Event Name (kevnm)
• %I Instrument (kinst)
• %N Network (knetwk)
• %S Station (kstnm)
• %C Channel (kcmpnm)
• %H Location or Hole (khole)
• %L Location or Hole (khole), if value is "" or undefined, use "--".
• %t Relative time formatting (seconds from reference) 12.64 . All relative timing uses lowercase characters
  • %tb begin time
  • %te end time
  • %to origin time
  • %ta arrival time
  • %t0 .. %t9 time picks 0 to 9
• %T Absolute time formatting, e.g. 1994/06/09T00:33:16.123 . All absolute timing uses uppercase characters
  • %tB begin time
  • %tE end time
  • %tO origin time
  • %tA arrival time
  • %t0 .. %t9 time picks 0 to 9
• %Z alias for %N.%S.%H.%C net.sta.loc.cha
• %R alias for %N %S %L %C %TB %TE similar to a data request

Parameters

dst	Output character string
n	Length of dst
fmt	Formatting string
s	sac file to get values from

Returns

full length of dst, -1 on error

Example

• Set and get a Net.Sta.Loc.Cha Code

char code[32] = {0};
sac *s = sac_new();
sac_set_string(s, SAC_NET, "CI");
sac_set_string(s, SAC_STA, "PAS");
sac_set_string(s, SAC_LOC, "");
sac_set_string(s, SAC_CHA, "BHZ");

sac_fmt(code, sizeof code, "%Z", s);
assert_eq(strcmp(code, "CI.PAS..BHZ"), 0);

sac_free()

void sac_free

(

sac *

s

)

free a sac file structure

free a sac file structure. Free any data components, meta data, header and other associated components

Parameters

s	sac file struture to free

Example of creating and freeing a sac file in memory

sac *s = sac_new();
sac_set_int(s, SAC_NPTS, 100);
sac_alloc(s);
assert_ne(s->y, NULL);
sac_free(s);

sac_get_float()

int sac_get_float	(	sac *	s,
		int	hdr,
		double *	v
	)

Get a floating point value from a sac file.

Get a floating point value from a sac file. If the header version is 6, values are always from the 32-bit header. If the header version is 7, values from the 64-bit header are preferred, otherwise the 32-bit header values are used.

Parameters

s	sac file
hdr	HeaderID
v	output floating point value

Returns

status code, 0 on failure, 1 on success

double dt = 0.0;
sac *s = sac_new();
sac_set_float(s, SAC_DELTA, 0.25);
sac_get_float(s, SAC_DELTA, &dt);
assert_eq(dt, 0.25);

sac_get_int()

int sac_get_int	(	sac *	s,
		int	hdr,
		int *	v
	)

Get a integer value from a sac file.

Get a integer value from a sac file

Parameters

s	sac file
hdr	HeaderID
v	output integer value

Returns

status code, 0 on failure, 1 on success

int n = 0;
sac *s = sac_new();
sac_set_int(s, SAC_NPTS, 2600);
sac_get_int(s, SAC_NPTS, &n);
assert_eq(n, 2600);

sac_get_pick()

int sac_get_pick	(	sac *	s,
		int	n,
		double *	t
	)

Get a timing pick.

Get a timing pick from the sac header

Parameters

s	sac file
n	pick number
t	return value (64-bit value)

Returns

1 on success, 0 on failure

Example of getting a time pick by its number, 0 to 9

int nerr = 0;
double t = 0.0;
sac *s = sac_read("t/test_io_small.sac", &nerr);
sac_set_pick(s, 3, 13.50);
sac_get_pick(s, 3, &t);
assert_eq(t, 13.50);

sac_get_string()

int sac_get_string	(	sac *	s,
		int	hdr,
		char *	v,
		size_t	n
	)

Get a character string from a sac file.

Get a character string from a sac file

Parameters

s	sac file
hdr	HeaderID, Listing of string ::HeadersID is below
v	output character string
n	length of v

Returns

status code, 0 on failure, 1 on success

Note

HeaderID

• SAC_STA / SAC_KSTNM
• SAC_EVENT / SAC_KEVNM
• SAC_KHOLE / SAC_LOC
• SAC_KO
• SAC_KA
• SAC_KT0 .. SAC_KT9
• SAC_KF
• SAC_KUSER0 .. SAC_KUSER2
• SAC_CHA / SAC_CHAN / SAC_KCMPNM
• SAC_NET / SAC_KNETWK
• SAC_DATRD
• SAC_INST / SAC_KINST
• SAC_DATE - "Mon. Day (DOY), Year"
• SAC_TIME - "H:M:S.ms"
• SAC_FILENAME - filename of the sac file
• SAC_AMARKER - "value (name)"
• SAC_OMARKER - "value (name)"
• SAC_T0MARKER .. SAC_T9MARKER - "value (name)"
• SAC_STCMP - "STATION CHANNEL"

  char sta[18] = {0};
  sac *s = sac_new();
  // Set a string, SAC_KSTNM and SAC_STA are the same
  sac_set_string(s, SAC_KSTNM, "PAS");
  sac_get_string(s, SAC_STA, sta, sizeof sta);
  assert_eq(strcmp(sta, "PAS"), 0);
  
  // Most input strings are truncated at 8 characters
  //     SAC_KNETWK and SAC_NET are the same
  sac_set_string(s, SAC_KNETWK, "123456789012345");
  sac_get_string(s, SAC_NET, sta, sizeof sta);
  assert_eq(strcmp(sta, "12345678"), 0);
  
  // ... except for the Event name, it gets 16 characters
  //     SAC_KEVNM and SAC_EVENT are the same
  sac_set_string(s, SAC_EVENT, "1234567890123456789");
  sac_get_string(s, SAC_KEVNM, sta, sizeof sta);
  assert_eq(strcmp(sta, "1234567890123456"), 0);

sac_get_time()

int sac_get_time	(	sac *	s,
		int	hdr,
		timespec64 *	t
	)

Get time value from sac file.

Get time value from sac file

Parameters

s	sac file
hdr	header index value
t	timespec64 output value

Returns

1 in success, 0 on failure

timespec64 t = {-1,-1};
timespec64 b = {-1,-1};
sac *s = sac_new();
timespec64_parse("1970/01/02T00:00:00", &t);
sac_set_time(s, t);
sac_set_float(s, SAC_B, 0.0);

sac_get_time(s, SAC_B, &b);
assert_eq(b.tv_sec, 60*60*24);
assert_eq(b.tv_nsec, 0);

sac_get_time_ref()

int sac_get_time_ref	(	sac *	s,
		timespec64 *	t
	)

Get the reference time from a sac file.

Get the refereence time from a sac file

Parameters

s	sac file
t	timespec64 output value

Returns

1 on success, 0 in failure

timespec64 t = {-1,-1};
sac *s = sac_new();
sac_set_int(s, SAC_YEAR, 1970);
sac_set_int(s, SAC_DAY,  2);
sac_set_int(s, SAC_HOUR, 0);
sac_set_int(s, SAC_MIN,  0);
sac_set_int(s, SAC_SEC,  0);
sac_set_int(s, SAC_MSEC, 0);

sac_get_time_ref(s, &t);
assert_eq(t.tv_sec, 60*60*24);
assert_eq(t.tv_nsec, 0);

sac_hdr_defined()

int sac_hdr_defined	(	sac *	s,
			...
	)

Check if multiple header values are defined.

Check if mulutple header values are defined

Parameters

s	sac file
...	HeaderID list, NULL terminatated

Returns

0 if any are undefined, 1 if all are defined

sac *s = sac_new();
int ok = sac_hdr_defined(s, SAC_EVEN, SAC_FILE_TYPE, NULL);
assert_eq(ok, 1);

sac_header_copy()

void sac_header_copy	(	sac *	to,
		sac *	from
	)

copy the sac header

copy the sac header from from to to

Parameters

to	destination
from	source

sac *new = NULL;
int n_old = 0, n_new = 0;
int nerr = 0;

// Read in an existing file
sac *old = sac_read("t/test_io_small.sac", &nerr);
assert_eq(nerr, 0);

// Create a new sac file
new = sac_new();
sac_get_int(new, SAC_NPTS, &n_new);
assert_eq(n_new, SAC_INT_UNDEFINED);

// Copy header from old file to new file
sac_header_copy(new, old);

// Compare number of points
sac_get_int(new, SAC_NPTS, &n_new);
sac_get_int(old, SAC_NPTS, &n_old);
assert_eq(n_new, n_old);

sac_is_timeval()

int sac_is_timeval

(

int

hid

)

Identify if a header is a time value.

Check is the sac header value is a time value

Parameters

hid	sac HeaderID

Returns

True if header value is a time value type

assert_eq(sac_is_timeval(SAC_B), 1);
assert_eq(sac_is_timeval(SAC_DEPMAX), 0);

sac_meta_copy()

void sac_meta_copy	(	sac *	to,
		sac *	from
	)

copy the sac meta header

copy the sac meta header from from to to

Parameters

to	destination
from	source

sac *new = NULL;
char f_old[256]= {0}, f_new[256] = {0};
int nerr = 0;

// Read in an existing file
sac *old = sac_read("t/test_io_small.sac", &nerr);
assert_eq(nerr, 0);

// Create a new sac file
new = sac_new();
sac_get_string(new, SAC_FILENAME, f_new, sizeof f_new);
assert_eq(strcmp(f_new, ""), 0);

// Copy meta data from old file to new file
sac_meta_copy(new, old);

// Compare number of points
sac_get_string(new, SAC_FILENAME, f_new, sizeof f_new);
sac_get_string(old, SAC_FILENAME, f_old, sizeof f_old);
assert_eq(strcmp(f_new, f_old), 0);

sac_new()

sac * sac_new

(

)

create a new sac file structure

create a new sac file structure. Header and meta data are allocated. Data components are not allocated and should be done with sac_alloc() after setting the type of file and the number of data points

Returns

newly created sac file structure

Create a new sac file in memory

int v = 0;
sac *s = sac_new();
assert_ne(s, NULL);
assert_eq(s->x, NULL);
assert_eq(s->y, NULL);

sac_get_int(s, SAC_EVEN, &v);
assert_eq(v, TRUE);

sac_get_int(s, SAC_POLARITY, &v);
assert_eq(v, FALSE);

sac_get_int(s, SAC_OVERWRITE, &v);
assert_eq(v, TRUE);

sac_get_int(s, SAC_CALC_DIST_AZ, &v);
assert_eq(v, TRUE);

sac_get_int(s, SAC_FILE_TYPE, &v);
assert_eq(v, ITIME);

sac_read()

sac * sac_read	(	char *	filename,
		int *	nerr
	)

Read a sac file.

Read a sac file, data and header

Parameters

filename	file to read data and header from
nerr	status code, 0 on success, non-zero on header

Returns

sac file structure, NULL on failure

Reading a sac file should result in a pointer to a sac-file structure

int nerr = 0;
sac *s = sac_read("t/test_io_small.sac", &nerr);
assert_ne(s, NULL);
assert_eq(nerr, 0);

Reading a file that does not exist will return a NULL pointer and an error code of 108

int nerr = 0;
sac *s = sac_read("non-existant-file", &nerr);
assert_eq(s, NULL);
assert_eq(nerr, 108);

Reading a file that exists but is not a sac file will return a NULL pointer and an error code of 1317

int nerr = 0;
sac *s = sac_read("sacio.c", &nerr);
assert_eq(s, NULL);
assert_eq(nerr, 1317);

sac_read_header()

sac * sac_read_header	(	char *	filename,
		int *	nerr
	)

Read a sac file header.

Read a sac file header

Parameters

filename	file to read sac header from
nerr	status code, 0 on success, non-zero on failure

Returns

sac file structure, NULL on failure

int nerr = 0;
sac *s = sac_read_header("t/test_io_small.sac", &nerr);
assert_eq(nerr, 0);
assert_eq(s->x, NULL);
assert_eq(s->y, NULL);
assert_ne(s->h, NULL);

sac_read_with_cut()

sac * sac_read_with_cut	(	char *	filename,
		char *	c1,
		double	t1,
		char *	c2,
		double	t2,
		enum CutAction	cutact,
		int *	nerr
	)

read a sac file while cutting

read a sac file while cutting

Parameters

filename	sac file to read
c1	reference time pick for start, see list below
t1	relative time from time pick c1
c2	reference time pick for end, see list below
t2	relative time ffrom time pick c2
cutact	Behavior of cut CutNone = 0 CutFatal = 1 CutUseBE = 2 CutFillZero = 3
nerr	Status code, 0 on success, non-zero on Error

Returns

read and cut file on success, NULL on error

Note

Time pick reference

• "Z" - Actual time
• "B" - Begin time
• "E" - End time
• "O" - Origin time
• "A" - First arrival time
• "F" - Final arrival time: SAC_F value
• "T0" to "T9" - t0 to t9 arrival times

int nerr = 0;
double b = 0, e = 0;
sac *s = sac_read_with_cut("t/test_io_small.sac", 
                           "Z", 10.0,
                           "Z", 30.0, CutUseBE, 
                           &nerr);
sac_get_float(s, SAC_B, &b);
sac_get_float(s, SAC_E, &e);
assert_eq(b, 10.0);
assert_eq(e, 30.0);

sac_set_float()

int sac_set_float	(	sac *	s,
		int	hdr,
		double	v
	)

Set a floating point value in a sac file.

Set a floating point value in a sac file. If the value is in the 64-bit header, the value is copied into the 32-bit and 64-bit header. If the value is only in the 32-bit header, the value is only copied there

Parameters

s	sac file
hdr	HeaderID
v	floating point to set

Returns

success code, 1 on success, 0 on failure

double dt = 0.0;
sac *s = sac_new();
sac_set_float(s, SAC_DELTA, 0.25);
sac_get_float(s, SAC_DELTA, &dt);
assert_eq(dt, 0.25);

sac_set_int()

int sac_set_int	(	sac *	s,
		int	hdr,
		int	v
	)

Set a integer value in a sac file.

Set a integer in a sac file

Parameters

s	sac file
hdr	HeaderID
v	integer value to set

Returns

success code, 1 on success, 0 on failure

int n = 0;
sac *s = sac_new();
sac_set_int(s, SAC_NPTS, 2600);
sac_get_int(s, SAC_NPTS, &n);
assert_eq(n, 2600);

sac_set_pick()

int sac_set_pick	(	sac *	s,
		int	n,
		double	value
	)

Set a time pick value.

Set a time pick value in a sac header

Parameters

s	sac file
n	pick number
value	timing value to set (64 bit value)

Returns

1 on success, 0 on failure

Exaple of setting the time pick t3 to 13.50

int nerr = 0;
double t = 0.0;
sac *s = sac_read("t/test_io_small.sac", &nerr);
sac_set_pick(s, 3, 13.50);
sac_get_float(s, SAC_T3, &t);
assert_eq(t, 13.50);

sac_set_string()

int sac_set_string	(	sac *	s,
		int	hdr,
		char *	v
	)

Set a character string in a sac file.

Set a character stirng in a sac file

Parameters

s	sac file
hdr	HeaderID, only valid sac header are setable
v	character string to set

Returns

success code, 1 on success, 0 on failure

char sta[18] = {0};
sac *s = sac_new();
// Set a string, SAC_KSTNM and SAC_STA are the same
sac_set_string(s, SAC_KSTNM, "PAS");
sac_get_string(s, SAC_STA, sta, sizeof sta);
assert_eq(strcmp(sta, "PAS"), 0);

// Most input strings are truncated at 8 characters
//     SAC_KNETWK and SAC_NET are the same
sac_set_string(s, SAC_KNETWK, "123456789012345");
sac_get_string(s, SAC_NET, sta, sizeof sta);
assert_eq(strcmp(sta, "12345678"), 0);

// ... except for the Event name, it gets 16 characters
//     SAC_KEVNM and SAC_EVENT are the same
sac_set_string(s, SAC_EVENT, "1234567890123456789");
sac_get_string(s, SAC_KEVNM, sta, sizeof sta);
assert_eq(strcmp(sta, "1234567890123456"), 0);

sac_set_time()

int sac_set_time	(	sac *	s,
		timespec64	t
	)

Set the reference time for a sac file, assumed to be the origin time

Parameters

s	sac file
t	origin time

Returns

1 on success, 0 on failure

Note

Reference time is set to the time provided, the time reference is set to ORIGIN, and all other times are references relative

Effective sac commands are:

SAC> ch o gmt 1994 160 00 33 16 230 SAC> ch iztype IO SAC> ch allt (-1.0 * &1,o)

int io = 0;
timespec64 t = {0,0}, t2 = {0,0};
sac *s = sac_new();
timespec64_parse("1970/01/02T00:00:00", &t);
sac_set_time(s, t);

sac_get_time_ref(s, &t2);
assert_eq(t2.tv_sec, 60*60*24);
assert_eq(t2.tv_nsec, 0);

sac_get_int(s, SAC_ZERO_TIME, &io);
assert_eq(io, IO);

sac_set_v6()

void sac_set_v6

(

sac *

s

)

Set the header version to 6.

Parameters

s

sac file

Set the header version to 6. See sac::sac_get_float() and sac::sac_set_float() for the details about how the different header version impact which floating point values are set and get.

int nerr = 0;
double t = 0.0;
sac *s = sac_read("t/test_io_small.sac", &nerr);
sac_set_float(s, SAC_DELTA, 1.0/3.0);

// Switch to the v7 header
sac_set_v7(s);

// Get delta, 64bit value, from the v7 footer
sac_get_float(s, SAC_DELTA, &t);
assert_eq(t, 1.0/3.0);

// Switch to the v6 header
sac_set_v6(s);

// Get delta, 32bit value, from the v6 header
sac_get_float(s, SAC_DELTA, &t);
assert_ne(t, 1.0/3.0);

sac_set_v7()

void sac_set_v7

(

sac *

s

)

Set the header version to 7.

Parameters

s

sac file

Set the header version to 7. See sac::sac_get_float() and sac::sac_set_float() for the details about how the different header version impact which floating point values are set and get.

int nerr = 0;
double t = 0.0;
sac *s = sac_read("t/test_io_small.sac", &nerr);
sac_set_float(s, SAC_DELTA, 1.0/3.0);

// Get delta, 32bit value, from the v6 header
sac_get_float(s, SAC_DELTA, &t);
assert_ne(t, 1.0/3.0);

// Switch to the v7 header
sac_set_v7(s);

// Get delta, 64bit value, from the v7 footer
sac_get_float(s, SAC_DELTA, &t);
assert_eq(t, 1.0/3.0);

sac_size()

off_t sac_size

(

sac *

s

)

Get the size of a sac file in bytes.

Get the size of a sac file in bytes if stored on disk

Parameters

s

sac file

Returns

size of file in bytes

size_t n = 0;
size_t sac_header_size = 632;
sac *s = sac_new();
n = sac_size(s);
assert_eq(n, 0);
sac_set_int(s, SAC_NPTS, 1);
n = sac_size(s);
assert_eq(n, sac_header_size + 4 * 1);

// Change to v7
sac_set_v7(s);
n = sac_size(s);
assert_eq(n, sac_header_size + 1 * 4 + 22 * 8);

sac_time_to_index()

int sac_time_to_index	(	sac *	s,
		double	t
	)

Convert a time to index.

Convert a time value to a data point index. All values are relative to the b value

Parameters

s	sac file
t	time value

Returns

index of data point associated with the time

int i = 0;
sac *s = sac_new();
sac_set_float(s, SAC_B, 10.0);
sac_set_float(s, SAC_DELTA, 0.1);

i = sac_time_to_index(s, 10.0);
assert_eq(i, 0);

i = sac_time_to_index(s, 20.0);
assert_eq(i, 100 );

sac_write()

void sac_write	(	sac *	s,
		char *	filename,
		int *	nerr
	)

write a sac file to disk

write a sac file to disk, header and data

Parameters

s	sac file to write to disk
filename	file to write to
nerr	status code, 0 on success, non-zero on error

Example of writing a sac file

int nerr = 0;
sac *s = sac_read("t/test_io_small.sac", &nerr);
assert_eq(nerr, 0);
sac_write(s, "t/test_io_small.sac.tmp", &nerr);
assert_eq(nerr, 0);

sac_write_header()

void sac_write_header	(	sac *	s,
		char *	filename,
		int *	nerr
	)

write a sac header to disk

write a sac header to disk

Parameters

s	sac header to write to disk
filename	file to write to, must exist and be a sac file
nerr	status code, 0 on success, non-zero on error

Example of writing a sac header

int nerr = 0;
sac *s = sac_read("t/test_io_small.sac", &nerr);
assert_eq(nerr, 0);
sac_write_header(s, "t/test_io_small.sac", &nerr);
assert_eq(nerr, 0);

A file that does not exist should return a error code of 108

int nerr = 0;
sac *s = sac_read("t/test_io_small.sac", &nerr);
assert_eq(nerr, 0);
sac_write_header(s, "non-existant-file", &nerr );
assert_eq(nerr, 108);

A file that is not a sac file should return an error code of 1317

int nerr = 0;
sac *s = sac_read("t/test_io_small.sac", &nerr);
assert_eq(nerr, 0);
sac_write_header(s, "sacio.c", &nerr);
assert_eq(nerr, 1317);