Error Handling
[System Utilities]

Collaboration diagram for Error Handling:

Files
file	psAstronomyErrors.h
	Contains the error text for the astronomy functions.
file	psCollectionsErrors.h
	Contains the error text for the collections functions.
file	psFileUtilsErrors.h
	Contains the error text for the dataIO functions.
file	psDataManipErrors.h
	Contains the error text for the data manipulation functions.
file	psImageErrors.h
	Contains the error text for the image functions.
file	psAbort.h
	Contains the declarations for the abort function.
file	psError.h
	Contains the declarations for the error reporting functions.
file	psErrorCodes.h
	Contains the error codes for the error classes.
file	psSysUtilsErrors.h
	Contains the error text for the system utility functions.
Data Structures
struct	psErr
	Error message object. More...
struct	psErrorDescription
	An error code with description. More...
Enumerations
enum	psErrorCode {   PS_ERR_NONE = 0, PS_ERR_BASE = 256, PS_ERR_UNKNOWN, PS_ERR_IO, PS_ERR_LOCATION_INVALID, PS_ERR_MEMORY_CORRUPTION, PS_ERR_MEMORY_DEREF_USAGE, PS_ERR_BAD_PARAMETER_VALUE, PS_ERR_BAD_PARAMETER_TYPE, PS_ERR_BAD_PARAMETER_NULL,   PS_ERR_BAD_PARAMETER_SIZE, PS_ERR_UNEXPECTED_NULL, PS_ERR_OS_CALL_FAILED, PS_ERR_N_ERR_CLASSES }
	enumeration of the static error code classes More...
Functions
void	psAbort (const char *name, const char *fmt,...)
	Reports an abort message to logging facility.
psErr *	psErrorGet (psS32 which)
	Get a error from the error stack.
psErr *	psErrorLast (void)
	Get last error put on the error stack.
void	psErrorClear (void)
	Clears the error stack.
psS32	psErrorGetStackSize ()
	Get the error stack depth.
void	psErrorStackPrint (FILE *fd, const char *fmt,...)
	Prints error stack to specified open file descriptor.
void	psErrorStackPrintV (FILE *fd, const char *fmt, va_list va)
	Prints error stack to specified open file descriptor.
psErrorCode	psError (psErrorCode code, psBool new, const char *fmt,...)
	Reports an error message to the logging facility.
void	psWarning (const char *fmt,...)
	Logs a warning message.
psErr *	psErrAlloc (const char *name, psErrorCode code, const char *msg)
	Create a new psErr struct.
psErrorDescription *	psErrorDescriptionAlloc (psErrorCode code, const char *description)
	Allocates a new psErrorDescription.
const char *	psErrorCodeString (psErrorCode code)
	Retrieves the description of an error code.
void	psErrorRegister (const psErrorDescription *errors, psS32 nerror)
	Register an error code.
psBool	p_psErrorUnregister (psErrorCode code)
	Clears error codes registered via psErrorRegister.

---

Enumeration Type Documentation

enum psErrorCode

enumeration of the static error code classes Enumeration values: PS_ERR_NONE  not an error PS_ERR_BASE  base error Any psErrorCode less than this should be taken to be valid values of errno PS_ERR_UNKNOWN  unknown error PS_ERR_IO  I/O error. PS_ERR_LOCATION_INVALID  specified location is unknown PS_ERR_MEMORY_CORRUPTION  memory corruption detected PS_ERR_MEMORY_DEREF_USAGE  dereferenced memory still used PS_ERR_BAD_PARAMETER_VALUE  parameter is out-of-range PS_ERR_BAD_PARAMETER_TYPE  parameter is of unsupported type PS_ERR_BAD_PARAMETER_NULL  parameter is null PS_ERR_BAD_PARAMETER_SIZE  size of parameter's data is outside of acceptable range. PS_ERR_UNEXPECTED_NULL  unexpected NULL found PS_ERR_OS_CALL_FAILED  unexpected result from an OS standard library call PS_ERR_N_ERR_CLASSES  end marker - should not be used as a true error Definition at line 37 of file psErrorCodes.h.

---

Function Documentation

psBool p_psErrorUnregister (  psErrorCode  code  )

Clears error codes registered via psErrorRegister. Returns: psBool TRUE if given errorcode was removed, otherwise FALSE. Parameters: code  the error code to find and remove

void psAbort (  const char *  name, const char *  fmt,   ... )

Reports an abort message to logging facility. This function will invoke the psLogMsg function with a level of PS_LOG_ABORT and pass the parameters name and fmt to generate a proper log message. After logging, this function will call system abort function to abnormally terminate the program. Returns: void No return value Parameters: name  Source of abort such as file or function detected fmt  A printf style formatting statement defining msg

psErr* psErrAlloc (  const char *  name, psErrorCode  code, const char *  msg )

Create a new psErr struct. Creates a new psErr struct, making a copy of the parameters. Returns: psErr* new psErr object Parameters: name  Name of error in the form aaa.bbb.ccc code  Error class code msg  Error message

psErrorCode psError (  psErrorCode  code, psBool  new, const char *  fmt,   ... )

Reports an error message to the logging facility. This function will invoke the psLogMsg function with a level of PS_LOG_ERROR and pass the parameters name and fmt to generate a proper log message. This function modifies the error stack. Returns: psErrorCode the given error code Parameters: code  Error class code new  true if error originates at this location fmt  printf-style format of header line

void psErrorClear (  void   )

Clears the error stack. The error stack may be completely cleared with psErrorClear.

const char* psErrorCodeString (  psErrorCode  code  )

Retrieves the description of an error code. The routine psErrorCodeString returns the string associated with an error code. Returns: const char* the description associated with the given code. Parameters: code  the associated error code

psErrorDescription* psErrorDescriptionAlloc (  psErrorCode  code, const char *  description )

Allocates a new psErrorDescription. Returns: psErrorDescription* new psErrorDescription struct. Parameters: code  An error code description  the associated description

psErr* psErrorGet (  psS32  which  )

Get a error from the error stack. Previous errors on the stack are returned by psErrorGet (a value of 0 passed to psErrorGet is equivalent to a call to psErrorLast). if no error is at the which position, a non-NULL psErr is returned with code PS_ERR_NONE. Returns: Error message object at 'which' Parameters: which  position in the error stack. 0 is last error on stack.

psS32 psErrorGetStackSize (   )

Get the error stack depth. Returns: psS32 The number of items on the error stack

psErr* psErrorLast (  void   )

Get last error put on the error stack. The last error reported is available from psErrorLast; if no errors are current, a non-NULL psErr is returned with code PS_ERR_NONE. Returns: psErr* Reference to last error message on error stack

void psErrorRegister (  const psErrorDescription *  errors, psS32  nerror )

Register an error code. Any project needed to use psLib must define the necessary error codes and associated message strings. This function registers an array of error codes with the error handling subsystem. Parameters: errors  Array of error codes to register nerror  number of errors in input array

void psErrorStackPrint (  FILE *  fd, const char *  fmt,   ... )

Prints error stack to specified open file descriptor. The entire error stack may be printed to an open file descriptor by calling psErrorStackPrint; if and only if there are current errors, the printf-style string fmt is first printed to the file descriptor fd. In this printout, error codes are replaced by their string equivalents. Parameters: fd  destination file descriptor fmt  printf-style format of header line

void psErrorStackPrintV (  FILE *  fd, const char *  fmt, va_list  va )

Prints error stack to specified open file descriptor. The entire error stack may be printed to an open file descriptor by calling psErrorStackPrintV; if and only if there are current errors, the vprintf-style string fmt is first printed to the file descriptor fd. In this printout, error codes are replaced by their string equivalents. Parameters: fd  destination file descriptor fmt  printf-style format of header line va  any parameters required in fmt

void psWarning (  const char *  fmt,   ... )

Logs a warning message. This procedure logs a message to the destination set by a prior call to psLogSetDestination(), This is equivalent to calling psLogMsg with a level of PS_LOG_WARN. Parameters: fmt  printf-style format of header line

---