General Utility Functions

General utility functions. More...

Data Structures
struct	DLstrlist

Functions
const char *	dlp_strerror (void)
	Return a description of the last system error.
int	dlp_openfile (const char *filename, char perm)
	Open a file stream.
int64_t	dlp_time (void)
	Determine the current system time.
void	dlp_usleep (unsigned long int useconds)
	Sleep for a specified number of microseconds.
int	dlp_genclientid (char *progname, char *clientid, size_t maxsize)
	Generate a DataLink client ID from system & process information.
int	dl_splitstreamid (char *streamid, char *w, char *x, char *y, char *z, char *type)
	Split a stream ID into separate components: "W_X_Y_Z/TYPE".
int	dl_bigendianhost (void)
	Determine byte order of host machine.
double	dl_dabs (double value)
	Return absolute value of double value.
int	dl_readline (int fd, char *buffer, int buflen)
	Read a line from a file stream.
int	dl_strparse (const char *string, const char *delim, DLstrlist **list)
	Parse/split a string on a specified delimiter.
int	dl_strncpclean (char *dest, const char *source, int length)
	Copy a string while removing space charaters.
int	dl_addtostring (char **string, char *add, char *delim, int maxlen)
	Concatinate one string to another growing the destination as needed.

Detailed Description

General utility functions.

---

Data Structure Documentation

DLstrlist

struct DLstrlist

Function Documentation

dlp_strerror()

const char * dlp_strerror

(

void

)

Return a description of the last system error.

Returns

A description of the last system error, in the case of WIN this will be the last Windows Sockets error.

dlp_openfile()

int dlp_openfile	(	const char *	filename,
		char	perm
	)

Open a file stream.

Open a specified file and return the file descriptor. The perm character is interpreted the following way:

perm: 'r', open file with read-only permissions 'w', open file with read-write permissions, creating if necessary.

Parameters

filename	File to open
perm	Permission flag

Returns

The return value of open(), generally this is a positive file descriptor on success and -1 on error.

dlp_time()

int64_t dlp_time

(

void

)

Determine the current system time.

Determine the current time from the system as a dltime_t value. On the WIN platform this function has millisecond resulution, on Unix platforms this function has microsecond resolution.

Returns

Current time as a dltime_t value.

dlp_usleep()

void dlp_usleep

(

unsigned long int

useconds

)

Sleep for a specified number of microseconds.

Sleep for a given number of microseconds. Under WIN use SleepEx() and for all others use the POSIX.4 nanosleep(), which can be interrupted by signals.

Parameters

useconds

Microseconds to sleep.

dlp_genclientid()

int dlp_genclientid	(	char *	progname,
		char *	clientid,
		size_t	maxsize
	)

Generate a DataLink client ID from system & process information.

Generate a client ID composed of the program name, the current user name and the current process ID as a string where the fields are separated by colons:

"progname:username:pid:arch"

The client ID string is written into a supplied string which must already be allocated.

Parameters

progname	Name of program, usually argv[0]
clientid	Generated client ID string will be written to this string
maxsize	Maximum bytes to write to clientid string.

Returns

the number of characters written to clientid on success and -1 on error.

dl_splitstreamid()

int dl_splitstreamid	(	char *	streamid,
		char *	w,
		char *	x,
		char *	y,
		char *	z,
		char *	type
	)

Split a stream ID into separate components: "W_X_Y_Z/TYPE".

Split stream ID into separate components from the composite form: "W_X_Y_Z/TYPE" where the underscores and slash separate the components. Memory for each component must already be allocated. If a specific component is not desired set the appropriate argument to NULL.

While the stream name components are completely generic the (strongly) suggested form for geophysical data is "NET_STA_LOC_CHAN/TYPE" where NETwork, STAtion, LOCation and CHANnel follow the FDSN SEED conventions.

Returns

0 on success and -1 on error.

dl_bigendianhost()

int dl_bigendianhost

(

void

)

Determine byte order of host machine.

Determine the byte order of the host machine. Due to the lack of portable defines to determine host byte order this run-time test is provided. The code actually tests for little-endianess, the only other alternative is assumed to be big endian.

Returns

0 if the host is little endian, otherwise 1.

dl_dabs()

double dl_dabs

(

double

value

)

Return absolute value of double value.

Determine the absolute value of an input double, actually just test if the input double is positive multiplying by -1.0 if not and return it.

Returns

Positive value of input double.

dl_readline()

int dl_readline	(	int	fd,
		char *	buffer,
		int	buflen
	)

Read a line from a file stream.

Read characters from a stream (specified as a file descriptor) until a newline character '
' is read and place them into the supplied buffer. Reading stops when either a newline character is read or buflen-1 characters have been read. The buffer will always contain a NULL-terminated string.

Returns

The number of characters read on success and -1 on error.

dl_strparse()

int dl_strparse	(	const char *	string,
		const char *	delim,
		DLstrlist **	list
	)

Parse/split a string on a specified delimiter.

Splits a 'string' on 'delim' and puts each part into a linked list pointed to by 'list' (a pointer to a pointer). The last entry has it's 'next' set to 0. All elements are NULL terminated strings.

It is up to the caller to free the memory associated with the returned list. To facilitate freeing this special string list dl_strparse() can be called with both 'string' and 'delim' set to NULL and then the linked list is traversed and the memory used is free'd and the list pointer is set to NULL.

Parameters

string	String to parse/split
delim	Delimiter to split string on
list	Returned list of sub-strings.

Returns

The number of elements added to the list, or 0 when freeing the linked list.

dl_strncpclean()

int dl_strncpclean	(	char *	dest,
		const char *	source,
		int	length
	)

Copy a string while removing space charaters.

Copy length characters from source to dest while removing all spaces. The result is left justified and always null terminated. The source string must have at least length characters and the destination string must have enough room needed for the non-space characters within length and the null terminator.

Parameters

dest	Destination string
source	String to copy
length	Copy up to a maximum of this many characters to dest

Returns

The number of characters (not including the null terminator) in the destination string.

dl_addtostring()

int dl_addtostring	(	char **	string,
		char *	add,
		char *	delim,
		int	maxlen
	)

Concatinate one string to another growing the destination as needed.

Concatinate one string to another with a delimiter in-between growing the destination string as needed up to a maximum length.

Parameters

string	Destination string to be added to
add	String to add to string
delim	Optional delimiter between added strings (cannot be NULL, but can be an empty string)
maxlen	Maximum number of bytes to grow string

Returns

0 on success, -1 on memory allocation error and -2 when string would grow beyond maximum length.