Poster of Linux kernelThe best gift for a Linux geek
Error handling

Error handling

Section: BrlAPI (3) Updated: Tue Mar 1 2011
Local index Up
 

NAME

Error handling -

How to handle errors.

 

Data Structures


struct brlapi_error_t
 

Defines


#define BRLAPI_ERROR_SUCCESS 0

#define BRLAPI_ERROR_NOMEM 1

#define BRLAPI_ERROR_TTYBUSY 2

#define BRLAPI_ERROR_DEVICEBUSY 3

#define BRLAPI_ERROR_UNKNOWN_INSTRUCTION 4

#define BRLAPI_ERROR_ILLEGAL_INSTRUCTION 5

#define BRLAPI_ERROR_INVALID_PARAMETER 6

#define BRLAPI_ERROR_INVALID_PACKET 7

#define BRLAPI_ERROR_CONNREFUSED 8

#define BRLAPI_ERROR_OPNOTSUPP 9

#define BRLAPI_ERROR_GAIERR 10

#define BRLAPI_ERROR_LIBCERR 11

#define BRLAPI_ERROR_UNKNOWNTTY 12

#define BRLAPI_ERROR_PROTOCOL_VERSION 13

#define BRLAPI_ERROR_EOF 14

#define BRLAPI_ERROR_EMPTYKEY 15

#define BRLAPI_ERROR_DRIVERERROR 16

#define BRLAPI_ERROR_AUTHENTICATION 17

#define brlapi_error (*brlapi_error_location())

#define brlapi_errno (brlapi_error.brlerrno)

#define brlapi_libcerrno (brlapi_error.libcerrno)

#define brlapi_gaierrno (brlapi_error.gaierrno)

#define brlapi_errfun (brlapi_error.errfun)
 

Typedefs


typedef uint32_t brlapi_packetType_t

typedef void(BRLAPI_STDCALL * brlapi_exceptionHandler_t )(int error, brlapi_packetType_t type, const void *packet, size_t size)

typedef void(BRLAPI_STDCALL * brlapi__exceptionHandler_t )(brlapi_handle_t *handle, int error, brlapi_packetType_t type, const void *packet, size_t size)
 

Functions


void BRLAPI_STDCALL brlapi_perror (const char *s)

brlapi_error_t *BRLAPI_STDCALL brlapi_error_location (void)

const char *BRLAPI_STDCALL brlapi_strerror (const brlapi_error_t *error)

const char *BRLAPI_STDCALL brlapi_getPacketTypeName (brlapi_packetType_t type)

int BRLAPI_STDCALL brlapi_strexception (char *buffer, size_t bufferSize, int error, brlapi_packetType_t type, const void *packet, size_t packetSize)

int BRLAPI_STDCALL brlapi__strexception (brlapi_handle_t *handle, char *buffer, size_t bufferSize, int error, brlapi_packetType_t type, const void *packet, size_t packetSize)

brlapi_exceptionHandler_t BRLAPI_STDCALL brlapi_setExceptionHandler (brlapi_exceptionHandler_t handler)

brlapi__exceptionHandler_t BRLAPI_STDCALL brlapi__setExceptionHandler (brlapi_handle_t *handle, brlapi__exceptionHandler_t handler)

void BRLAPI_STDCALL brlapi_defaultExceptionHandler (int error, brlapi_packetType_t type, const void *packet, size_t size)

void BRLAPI_STDCALL brlapi__defaultExceptionHandler (brlapi_handle_t *handle, int error, brlapi_packetType_t type, const void *packet, size_t size)
 

Variables


const char * brlapi_errlist []

const int brlapi_nerr

brlapi_error_t brlapi_error

int brlapi_errno

int brlapi_libcerrno

int brlapi_gaierrno

const char * brlapi_errfun
 

Detailed Description

When a function fails, brlapi_errno will hold an error code to explain why it failed. It should always be reported somehow.

Although most errors are reported that way, some (called exceptions) are reported asynchronously for efficiency reasons, because they always just report a programming error. The affected functions are: brlapi_setFocus, brlapi_write* and brlapi_sendRaw. When they happen, the next call to brlapi_something will close the connection and call the exception handler. If the exception handler returns, the brlapi_something function will return an end-of-file error.

The default exception handler (brlapi_defaultExceptionHandler()) dumps the guilty packet before abort()ing. It can be replaced by calling brlapi_setExceptionHandler(). For instance, the Java and Python bindings use this for raising a Java or Python exception that may be caught.  

Define Documentation

 

#define brlapi_errfun (brlapi_error.errfun)Cheat about the brlapi_errfun C token

 

#define brlapi_errno (brlapi_error.brlerrno)Cheat about the brlapi_errno C token

 

#define brlapi_error (*brlapi_error_location())Cheat about the brlapi_error C token

 

#define BRLAPI_ERROR_AUTHENTICATION 17Authentication failed

 

#define BRLAPI_ERROR_CONNREFUSED 8Connection refused

 

#define BRLAPI_ERROR_DEVICEBUSY 3A connection is already using RAW or suspend mode

 

#define BRLAPI_ERROR_DRIVERERROR 16Packet returned by driver too large

 

#define BRLAPI_ERROR_EMPTYKEY 15Key file empty

 

#define BRLAPI_ERROR_EOF 14Unexpected end of file

 

#define BRLAPI_ERROR_GAIERR 10Getaddrinfo error

 

#define BRLAPI_ERROR_ILLEGAL_INSTRUCTION 5Forbiden in current mode

 

#define BRLAPI_ERROR_INVALID_PACKET 7Invalid size

 

#define BRLAPI_ERROR_INVALID_PARAMETER 6Out of range or have no sense

 

#define BRLAPI_ERROR_LIBCERR 11Libc error

 

#define BRLAPI_ERROR_NOMEM 1Not enough memory

 

#define BRLAPI_ERROR_OPNOTSUPP 9Operation not supported

 

#define BRLAPI_ERROR_PROTOCOL_VERSION 13Bad protocol version

 

#define BRLAPI_ERROR_SUCCESS 0Success

 

#define BRLAPI_ERROR_TTYBUSY 2A connection is already running in this tty

 

#define BRLAPI_ERROR_UNKNOWN_INSTRUCTION 4Not implemented in protocol

 

#define BRLAPI_ERROR_UNKNOWNTTY 12Couldn't find out the tty number

 

#define brlapi_gaierrno (brlapi_error.gaierrno)Cheat about the brlapi_gaierrno C token

 

#define brlapi_libcerrno (brlapi_error.libcerrno)Cheat about the brlapi_libcerrno C token

 

Typedef Documentation

 

typedef void(BRLAPI_STDCALL * brlapi__exceptionHandler_t)(brlapi_handle_t *handle, int error, brlapi_packetType_t type, const void *packet, size_t size)

 

typedef void(BRLAPI_STDCALL * brlapi_exceptionHandler_t)(int error, brlapi_packetType_t type, const void *packet, size_t size)Types for exception handlers

Types of exception handlers which are to be given to brlapi_setExceptionHandler() and brlapi__setExceptionHandler().

Parameters:

handle is the handle corresponding to the guilty connection;
error is a BRLAPI_ERROR_ error code;
type is the type of the guilty packet;
packet points to the content of the guilty packet (might be a little bit truncated);
size gives the guilty packet's size.

 

typedef uint32_t brlapi_packetType_tType for packet type. Only unsigned can cross networks, 32bits

 

Function Documentation

 

void BRLAPI_STDCALL brlapi__defaultExceptionHandler (brlapi_handle_t *handle, interror, brlapi_packetType_ttype, const void *packet, size_tsize)

 

brlapi__exceptionHandler_t BRLAPI_STDCALL brlapi__setExceptionHandler (brlapi_handle_t *handle, brlapi__exceptionHandler_thandler)

 

int BRLAPI_STDCALL brlapi__strexception (brlapi_handle_t *handle, char *buffer, size_tbufferSize, interror, brlapi_packetType_ttype, const void *packet, size_tpacketSize)

 

void BRLAPI_STDCALL brlapi_defaultExceptionHandler (interror, brlapi_packetType_ttype, const void *packet, size_tsize)

 

brlapi_error_t* BRLAPI_STDCALL brlapi_error_location (void)Get per-thread error location

In multithreaded software, brlapi_error is thread-specific, so api.h cheats about the brlapi_error token and actually calls brlapi_error_location().

This gets the thread specific location of global variable brlapi_error  

const char* BRLAPI_STDCALL brlapi_getPacketTypeName (brlapi_packetType_ttype)Get plain packet type

brlapi_getPacketTypeName() returns the plain packet type name corresponding to its argument.  

void BRLAPI_STDCALL brlapi_perror (const char *s)Print a BrlAPI error message

brlapi_perror() reads brlapi_error, and acts just like perror().  

brlapi_exceptionHandler_t BRLAPI_STDCALL brlapi_setExceptionHandler (brlapi_exceptionHandler_thandler)Set a new exception handler

brlapi_setExceptionHandler() replaces the previous exception handler with the handler parameter. The previous exception handler is returned to make chaining error handlers possible.

The default handler just prints the exception and abort()s.  

const char* BRLAPI_STDCALL brlapi_strerror (const brlapi_error_t *error)Get plain error message

brlapi_strerror() returns the plain error message corresponding to its argument.  

int BRLAPI_STDCALL brlapi_strexception (char *buffer, size_tbufferSize, interror, brlapi_packetType_ttype, const void *packet, size_tpacketSize)Describes an exception

brlapi_strexception() puts a text describing the given exception in buffer.

The beginning of the guilty packet is dumped as a sequence of hex bytes.

Returns:

the size of the text describing the exception, following snprintf()'s semantics.

 

Variable Documentation

 

const char* brlapi_errfunShorthand for brlapi_error.errfun

 

const char* brlapi_errlist[]Error message list

These are the string constants used by brlapi_perror().  

int brlapi_errnoShorthand for brlapi_error.errno

 

brlapi_error_t brlapi_errorGlobal variable brlapi_error

brlapi_error is a global left-value containing the last error information. Its errno field is not reset to BRLAPI_ERROR_SUCCESS on success.

This information may be copied in brlapi_error_t variables for later use with the brlapi_strerror function.  

int brlapi_gaierrnoShorthand for brlapi_error.gaierrno

 

int brlapi_libcerrnoShorthand for brlapi_error.libcerrno

 

const int brlapi_nerrNumber of error messages

 

Author

Generated automatically by Doxygen for BrlAPI from the source code.


 

Index

NAME
Data Structures
Defines
Typedefs
Functions
Variables
Detailed Description
Define Documentation
#define brlapi_errfun (brlapi_error.errfun)Cheat about the brlapi_errfun C token
#define brlapi_errno (brlapi_error.brlerrno)Cheat about the brlapi_errno C token
#define brlapi_error (*brlapi_error_location())Cheat about the brlapi_error C token
#define BRLAPI_ERROR_AUTHENTICATION 17Authentication failed
#define BRLAPI_ERROR_CONNREFUSED 8Connection refused
#define BRLAPI_ERROR_DEVICEBUSY 3A connection is already using RAW or suspend mode
#define BRLAPI_ERROR_DRIVERERROR 16Packet returned by driver too large
#define BRLAPI_ERROR_EMPTYKEY 15Key file empty
#define BRLAPI_ERROR_EOF 14Unexpected end of file
#define BRLAPI_ERROR_GAIERR 10Getaddrinfo error
#define BRLAPI_ERROR_ILLEGAL_INSTRUCTION 5Forbiden in current mode
#define BRLAPI_ERROR_INVALID_PACKET 7Invalid size
#define BRLAPI_ERROR_INVALID_PARAMETER 6Out of range or have no sense
#define BRLAPI_ERROR_LIBCERR 11Libc error
#define BRLAPI_ERROR_NOMEM 1Not enough memory
#define BRLAPI_ERROR_OPNOTSUPP 9Operation not supported
#define BRLAPI_ERROR_PROTOCOL_VERSION 13Bad protocol version
#define BRLAPI_ERROR_SUCCESS 0Success
#define BRLAPI_ERROR_TTYBUSY 2A connection is already running in this tty
#define BRLAPI_ERROR_UNKNOWN_INSTRUCTION 4Not implemented in protocol
#define BRLAPI_ERROR_UNKNOWNTTY 12Couldn't find out the tty number
#define brlapi_gaierrno (brlapi_error.gaierrno)Cheat about the brlapi_gaierrno C token
#define brlapi_libcerrno (brlapi_error.libcerrno)Cheat about the brlapi_libcerrno C token
Typedef Documentation
typedef void(BRLAPI_STDCALL * brlapi__exceptionHandler_t)(brlapi_handle_t *handle, int error, brlapi_packetType_t type, const void *packet, size_t size)
typedef void(BRLAPI_STDCALL * brlapi_exceptionHandler_t)(int error, brlapi_packetType_t type, const void *packet, size_t size)Types for exception handlers
typedef uint32_t brlapi_packetType_tType for packet type. Only unsigned can cross networks, 32bits
Function Documentation
void BRLAPI_STDCALL brlapi__defaultExceptionHandler (brlapi_handle_t *handle, interror, brlapi_packetType_ttype, const void *packet, size_tsize)
brlapi__exceptionHandler_t BRLAPI_STDCALL brlapi__setExceptionHandler (brlapi_handle_t *handle, brlapi__exceptionHandler_thandler)
int BRLAPI_STDCALL brlapi__strexception (brlapi_handle_t *handle, char *buffer, size_tbufferSize, interror, brlapi_packetType_ttype, const void *packet, size_tpacketSize)
void BRLAPI_STDCALL brlapi_defaultExceptionHandler (interror, brlapi_packetType_ttype, const void *packet, size_tsize)
brlapi_error_t* BRLAPI_STDCALL brlapi_error_location (void)Get per-thread error location
const char* BRLAPI_STDCALL brlapi_getPacketTypeName (brlapi_packetType_ttype)Get plain packet type
void BRLAPI_STDCALL brlapi_perror (const char *s)Print a BrlAPI error message
brlapi_exceptionHandler_t BRLAPI_STDCALL brlapi_setExceptionHandler (brlapi_exceptionHandler_thandler)Set a new exception handler
const char* BRLAPI_STDCALL brlapi_strerror (const brlapi_error_t *error)Get plain error message
int BRLAPI_STDCALL brlapi_strexception (char *buffer, size_tbufferSize, interror, brlapi_packetType_ttype, const void *packet, size_tpacketSize)Describes an exception
Variable Documentation
const char* brlapi_errfunShorthand for brlapi_error.errfun
const char* brlapi_errlist[]Error message list
int brlapi_errnoShorthand for brlapi_error.errno
brlapi_error_t brlapi_errorGlobal variable brlapi_error
int brlapi_gaierrnoShorthand for brlapi_error.gaierrno
int brlapi_libcerrnoShorthand for brlapi_error.libcerrno
const int brlapi_nerrNumber of error messages
Author

This document was created by man2html, using the manual pages.
Time: 21:42:47 GMT, April 16, 2011