das2/util.h File Reference

Detailed Description

#include <das2/das1.h>
#include <stdbool.h>
#include <stdlib.h>
#include <stdarg.h>
#include <limits.h>

Defines
#define	DAS_OKAY 0
	success return code
#define	das2_error(nErrCode,...) das2_error_func(__FILE__, __func__, __LINE__, nErrCode, __VA_ARGS__ )
	Signal an error condition.
#define	XML_MAXPROPERTIES 100
	limit of number of properties per descriptor.
#define	XML_BUFFER_LENGTH 1000000
	The limit on xml packet length, in bytes.
#define	XML_ELEMENT_NAME_LENGTH 256
	The limit of xml element name length, in bytes.
#define	MAX_ARRAY_SIZE 1000
	maximum size of arrays for yTags, properties, etc
Typedefs
typedef int	ErrorCode
	return code type 0 indicates success, negative integer indicates failure
Functions
void	das2_abort_on_error (void)
	Error handling: Trigger Core Dumps.
void	das2_exit_on_error (void)
	Error handling: Normal Exit Set the library to call exit(ErrorCode) when a problem is detected.
void	das2_return_on_error (void)
	Error handling: Normal Return Set the library to return normally to the calling function with a return value that indicates a problem has occurred.
bool	das2_str2double (const char str, double pRes)
	Convert a string value to a 8-byte float, similar to strtod(3).
bool	das2_str2int (const char str, int pRes)
	Convert a string value to an integer with explicit over/underflow checks.
bool	das2_str2baseint (const char str, int base, int pRes)
	Convert a string to an integer with explicit base and overflow checking.
bool	das2_strn2baseint (const char str, int nLen, int base, int pRes)
	Convert an explicit length string to an integer with explicit base with over/underflow checks.
double *	das2_csv2doubles (const char s, int nitems)
	Parse a comma separated list of ASCII values into a double array.
char *	das2_doubles2csv (char buf, const double value, int nitems)
	Print an array of doubles into a string buffer.
const char *	das2_lib_version (void)
	Get the library version.
void	das2_store_str (char *psDest, size_t puLen, const char *sSrc)
	Store string in a buffer that is reallocated if need be.
bool	das2_isdir (const char *path)
	Is the path a directory.
bool	das2_isfile (const char *path)
	Is the path a file.
int	das2_dirlist (const char *sPath, char ppDirList[][NAME_MAX], size_t uMaxDirs, char cType)
	Get a sorted directory listing.

Define Documentation

#define das2_error	(	nErrCode,
		...		)	das2_error_func(__FILE__, __func__, __LINE__, nErrCode, __VA_ARGS__ )

Signal an error condition.

This routine is called throughout the code when an error condition arrises.

The default handler for error conditions prints the message provided to the standard error channel and then calls exit(nErrCode). To have the library call your handler instead use the das2_set_error_handler() function. To have the library abort with a core dump on an error use das2_abort_on_error().

Each source file in the code has it's own error code. Though it's probably not that useful to end users, the codes are provided here:

12 : buffer.c - DAS2ERR_BUF
13 : util.c - DAS2ERR_UTIL
14 : encoding.c - DAS2ERR_ENC
15 : units.c - DAS2ERR_UNITS
16 : descriptor.c - DAS2ERR_DESC
17 : plane.c - DAS2ERR_PLANE
18 : packet.c - DAS2ERR_PKT
19 : stream.c - DAS2ERR_STREAM
20 : oob.c - DAS2ERR_OOB
22 : das2io.c - DAS2ERR_IO
23 | dsdf.c - DAS2ERR_DSDF
24 : dft.c - DAS2ERR_DFT

Parameters:

	nErrCode	The value to return to the shell, should be one of the above.
	sFmt	An fprintf style format string

Returns:: By default this function never returns but if das2_continue_on_error has been called then the value of nErrCode is returned.

#define XML_MAXPROPERTIES 100

limit of number of properties per descriptor.

#define XML_BUFFER_LENGTH 1000000

The limit on xml packet length, in bytes.

(ascii encoding.)

#define XML_ELEMENT_NAME_LENGTH 256

The limit of xml element name length, in bytes.

Function Documentation

void das2_abort_on_error ( void )

Error handling: Trigger Core Dumps.

Call this function to have the library exit via an abort() call instead of using exit(ErrorCode). On most systems this will trigger the generation of a core file that can be used for debugging.

Warning:: : Calling this function prevents open file handles from being flushed to disk which will typically result in corrupted output.

void das2_exit_on_error ( void )

Error handling: Normal Exit Set the library to call exit(ErrorCode) when a problem is detected.

This is usually what you want and the library's default setting.

void das2_return_on_error ( void )

Error handling: Normal Return Set the library to return normally to the calling function with a return value that indicates a problem has occurred.

This will be the new default, but is not yet tested.

bool das2_str2double	(	const char *	str,
		double *	pRes
	)

Convert a string value to a 8-byte float, similar to strtod(3).

Parameters:

	str	the string to convert. Conversion stops at the first improper character. Whitespace and leading 0's are ignored in the input. The number is assumed to be in base 10, unless the first non-whitespace characters after the option as '+' or '-' sign are '0x'.
	pRes	The location to store the resulting 8-byte float.

Returns:: true if the conversion succeeded, false otherwise. Among other reason, conversion will fail if the resulting value won't fit in a 8 byte float.

bool das2_str2int	(	const char *	str,
		int *	pRes
	)

Convert a string value to an integer with explicit over/underflow checks.

Parameters:

	str	the string to convert. Conversion stops at the first improper character. Whitespace and leading 0's are ignored in the input. The number is assumed to be in base 10, unless the first non-whitespace characters after the optional '+' or '-' sign are '0x'.
	pRes	The location to store the resulting integer.

Returns:: true if the conversion succeeded, false otherwise.

bool das2_str2baseint	(	const char *	str,
		int	base,
		int *	pRes
	)

Convert a string to an integer with explicit base and overflow checking.

Parameters:

	str	the string to convert. Conversion stops at the first improper character. Whitespace and leading 0's are ignored in the input. No assumptions are made about the base of the string. So anything that is not a proper character is the given base is causes an error return.
	base	an integer from 1 to 60 inclusive.
	pRes	The location to store the resulting integer.

Returns:: true if the conversion succeeded, false otherwise.

bool das2_strn2baseint	(	const char *	str,
		int	nLen,
		int	base,
		int *	pRes
	)

Convert an explicit length string to an integer with explicit base with over/underflow checks.

Parameters:

	str	the string to convert. Conversion stops at the first improper character. Whitespace and leading 0's are ignored in the input. No assumptions are made about the base of the string. So anything that is not a proper character is the given base is causes an error return.
	base	an integer from 1 to 60 inclusive.
	pRes	The location to store the resulting integer.

Returns:: true if the conversion succeeded, false otherwise.

Will only inspect up to 64 non-whitespace characters when converting a value.

double* das2_csv2doubles	(	const char *	s,
		int *	nitems
	)

Parse a comma separated list of ASCII values into a double array.

Parameters:

`[in]`	s	The string of comma separated values
`[out]`	nitems	a pointer to an integer which will be set to the length of the newly allocated array.

Returns:: a new double array allocated on the heap.

char* das2_doubles2csv	(	char *	buf,
		const double *	value,
		int	nitems
	)

Print an array of doubles into a string buffer.

Prints an array of doubles into a string buffer with commas and spaces between each entry. Note there is no precision limit for the printing so the space needed to hold the array may 24 bytes times the number number of values, or more.

Todo:: this function is a potential source of buffer overruns, fix it.

Parameters:

`[out]`	buf	a pointer to the buffer to receive the printed values
`[in]`	value	an array of doubles
`[in]`	nitems	the number of items to print to the array

Returns:: A pointer to the supplied buffer.

const char* das2_lib_version ( void )

Get the library version.

Returns:: the version tag string for the das2 core library, or the string "untagged" if the version is unknown

void das2_store_str	(	char **	psDest,
		size_t *	puLen,
		const char *	sSrc
	)

Store string in a buffer that is reallocated if need be.

Parameters:

	psDest	a pointer to the storage location
	puLen	a pointer to the size of the storage location
	sSrc	the source string to store.

bool das2_isdir ( const char * path )

Is the path a directory.

Parameters:

path

The directory in question, passed to stat(2)

Returns:: true if path can be determined to be a directory, false otherwise

bool das2_isfile ( const char * path )

Is the path a file.

Parameters:

path

The file in question, passed to stat(2)

Returns:: true if path can be determined to be a file, false otherwise

int das2_dirlist	(	const char *	sPath,
		char	ppDirList[][NAME_MAX],
		size_t	uMaxDirs,
		char	cType
	)

Get a sorted directory listing.

Parameters:

	sPath	The path to the directory to read.
	ppDirList	A pointer to a 2-D character array where the first index is the directory item and the second index is the character position. The max value of the second index must be = NAME_MAX - 1. The value NAME_MAX is defined in the POSIX header limits.h
	uMaxDirs	The maximum number of directory entries that may be stored *
	cType	May be used to filter the items returned. If cType = 'f' only files will be return, if cType = 'd' then only directories will be returned. Any other value, including 0 will return both.

Returns:: On success the number of items in the directory not counting '.' and '..' are returned, on failure a negative error code is returned. Item names are sorted before return.

das2/util.h File Reference

Detailed Description

Defines

Typedefs

Functions

Define Documentation

Function Documentation