WCSLIB 8.2.2
Loading...
Searching...
No Matches
Data Structures | Macros | Functions
wcserr.h File Reference

Go to the source code of this file.

Data Structures

struct  wcserr
 Error message handling. More...
 

Macros

#define ERRLEN   (sizeof(struct wcserr)/sizeof(int))
 
#define WCSERR_SET(status)   err, status, function, __FILE__, __LINE__
 Fill in the contents of an error object.
 

Functions

int wcserr_enable (int enable)
 Enable/disable error messaging.
 
int wcserr_size (const struct wcserr *err, int sizes[2])
 Compute the size of a wcserr struct.
 
int wcserr_prt (const struct wcserr *err, const char *prefix)
 Print a wcserr struct.
 
int wcserr_clear (struct wcserr **err)
 Clear a wcserr struct.
 
int wcserr_set (struct wcserr **err, int status, const char *function, const char *file, int line_no, const char *format,...)
 Fill in the contents of an error object.
 
int wcserr_copy (const struct wcserr *src, struct wcserr *dst)
 Copy an error object.
 

Detailed Description

Most of the structs in WCSLIB contain a pointer to a wcserr struct as a member. Functions in WCSLIB that return an error status code can also allocate and set a detailed error message in this struct, which also identifies the function, source file, and line number where the error occurred.

For example:

struct prjprm prj;
if (prjini(&prj)) {
// Print the error message to stderr.
wcsprintf_set(stderr);
wcserr_prt(prj.err, 0x0);
}
int prjini(struct prjprm *prj)
Default constructor for the prjprm struct.
Projection parameters.
Definition prj.h:698
int wcserr_enable(int enable)
Enable/disable error messaging.
int wcserr_prt(const struct wcserr *err, const char *prefix)
Print a wcserr struct.
int wcsprintf_set(FILE *wcsout)
Set output disposition for wcsprintf() and wcsfprintf().

A number of utility functions used in managing the wcserr struct are for internal use only. They are documented here solely as an aid to understanding the code. They are not intended for external use - the API may change without notice!

Macro Definition Documentation

◆ ERRLEN

#define ERRLEN   (sizeof(struct wcserr)/sizeof(int))

◆ WCSERR_SET

#define WCSERR_SET (   status)    err, status, function, __FILE__, __LINE__

Fill in the contents of an error object.

INTERNAL USE ONLY.

WCSERR_SET() is a preprocessor macro that helps to fill in the argument list of wcserr_set(). It takes status as an argument of its own and provides the name of the source file and the line number at the point where invoked. It assumes that the err and function arguments of wcserr_set() will be provided by variables of the same names.

Function Documentation

◆ wcserr_enable()

int wcserr_enable ( int  enable)

Enable/disable error messaging.

wcserr_enable() enables or disables wcserr error messaging. By default it is disabled.

PLEASE NOTE: This function is not thread-safe.

Parameters
[in]enableIf true (non-zero), enable error messaging, else disable it.
Returns
Status return value:
  • 0: Error messaging is disabled.
  • 1: Error messaging is enabled.

◆ wcserr_size()

int wcserr_size ( const struct wcserr err,
int  sizes[2] 
)

Compute the size of a wcserr struct.

wcserr_size() computes the full size of a wcserr struct, including allocated memory.

Parameters
[in]errThe error object.
If NULL, the base size of the struct and the allocated size are both set to zero.
[out]sizesThe first element is the base size of the struct as returned by sizeof(struct wcserr). The second element is the total allocated size of the message buffer, in bytes.
Returns
Status return value:
  • 0: Success.

◆ wcserr_prt()

int wcserr_prt ( const struct wcserr err,
const char *  prefix 
)

Print a wcserr struct.

wcserr_prt() prints the error message (if any) contained in a wcserr struct. It uses the wcsprintf() functions.

Parameters
[in]errThe error object. If NULL, nothing is printed.
[in]prefixIf non-NULL, each output line will be prefixed with this string.
Returns
Status return value:
  • 0: Success.
  • 2: Error messaging is not enabled.

◆ wcserr_clear()

int wcserr_clear ( struct wcserr **  err)

Clear a wcserr struct.

wcserr_clear() clears (deletes) a wcserr struct.

Parameters
[in,out]errThe error object. If NULL, nothing is done. Set to NULL on return.
Returns
Status return value:
  • 0: Success.

◆ wcserr_set()

int wcserr_set ( struct wcserr **  err,
int  status,
const char *  function,
const char *  file,
int  line_no,
const char *  format,
  ... 
)

Fill in the contents of an error object.

INTERNAL USE ONLY.

wcserr_set() fills a wcserr struct with information about an error.

A convenience macro, WCSERR_SET, provides the source file and line number information automatically.

Parameters
[in,out]errError object.
If err is NULL, returns the status code given without setting an error message.
If *err is NULL, allocates memory for a wcserr struct (provided that status is non-zero).
[in]statusNumeric status code to set. If 0, then *err will be deleted and *err will be returned as NULL.
[in]functionName of the function generating the error. This must point to a constant string, i.e. in the initialized read-only data section ("data") of the executable.
[in]fileName of the source file generating the error. This must point to a constant string, i.e. in the initialized read-only data section ("data") of the executable such as given by the __FILE__ preprocessor macro.
[in]line_noLine number in the source file generating the error such as given by the __LINE__ preprocessor macro.
[in]formatFormat string of the error message. May contain printf-style %-formatting codes.
[in]...The remaining variable arguments are applied (like printf) to the format string to generate the error message.
Returns
The status return code passed in.

◆ wcserr_copy()

int wcserr_copy ( const struct wcserr src,
struct wcserr dst 
)

Copy an error object.

INTERNAL USE ONLY.

wcserr_copy() copies one error object to another. Use of this function should be avoided in general since the function, source file, and line number information copied to the destination may lose its context.

Parameters
[in]srcSource error object. If src is NULL, dst is cleared.
[out]dstDestination error object. If NULL, no copy is made.
Returns
Numeric status code of the source error object.