BrlAPI  0.8
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
Error handling

How to handle errors. More...

Data Structures

struct  brlapi_error_t
 

Macros

#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_STDCALLbrlapi_exceptionHandler_t) (int error, brlapi_packetType_t type, const void *packet, size_t size)
 
typedef void(BRLAPI_STDCALLbrlapi__exceptionHandler_t) (brlapi_handle_t *handle, int error, brlapi_packetType_t type, const void *packet, size_t size)
 

Enumerations

enum  brlapi_error {
  BRLAPI_ERROR_SUCCESS = 0 , BRLAPI_ERROR_SUCCESS = 0 , BRLAPI_ERROR_NOMEM = 1 , BRLAPI_ERROR_NOMEM = 1 ,
  BRLAPI_ERROR_TTYBUSY = 2 , BRLAPI_ERROR_TTYBUSY = 2 , BRLAPI_ERROR_DEVICEBUSY = 3 , BRLAPI_ERROR_DEVICEBUSY = 3 ,
  BRLAPI_ERROR_UNKNOWN_INSTRUCTION = 4 , BRLAPI_ERROR_UNKNOWN_INSTRUCTION = 4 , BRLAPI_ERROR_ILLEGAL_INSTRUCTION = 5 , BRLAPI_ERROR_ILLEGAL_INSTRUCTION = 5 ,
  BRLAPI_ERROR_INVALID_PARAMETER = 6 , BRLAPI_ERROR_INVALID_PARAMETER = 6 , BRLAPI_ERROR_INVALID_PACKET = 7 , BRLAPI_ERROR_INVALID_PACKET = 7 ,
  BRLAPI_ERROR_CONNREFUSED = 8 , BRLAPI_ERROR_CONNREFUSED = 8 , BRLAPI_ERROR_OPNOTSUPP = 9 , BRLAPI_ERROR_OPNOTSUPP = 9 ,
  BRLAPI_ERROR_GAIERR = 10 , BRLAPI_ERROR_GAIERR = 10 , BRLAPI_ERROR_LIBCERR = 11 , BRLAPI_ERROR_LIBCERR = 11 ,
  BRLAPI_ERROR_UNKNOWNTTY = 12 , BRLAPI_ERROR_UNKNOWNTTY = 12 , BRLAPI_ERROR_PROTOCOL_VERSION = 13 , BRLAPI_ERROR_PROTOCOL_VERSION = 13 ,
  BRLAPI_ERROR_EOF = 14 , BRLAPI_ERROR_EOF = 14 , BRLAPI_ERROR_EMPTYKEY = 15 , BRLAPI_ERROR_EMPTYKEY = 15 ,
  BRLAPI_ERROR_DRIVERERROR = 16 , BRLAPI_ERROR_DRIVERERROR = 16 , BRLAPI_ERROR_AUTHENTICATION = 17 , BRLAPI_ERROR_AUTHENTICATION = 17 ,
  BRLAPI_ERROR_READONLY_PARAMETER = 18 , BRLAPI_ERROR_READONLY_PARAMETER = 18
}
 

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)
 
size_t BRLAPI_STDCALL brlapi_strerror_r (const brlapi_error_t *error, char *buf, size_t buflen)
 
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
 
enum brlapi_error 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.

Macro Definition Documentation

◆ brlapi_errfun

#define brlapi_errfun   (brlapi_error.errfun)

Cheat about the brlapi_errfun C token

◆ brlapi_errno

#define brlapi_errno   (brlapi_error.brlerrno)

Cheat about the brlapi_errno C token

◆ brlapi_error

Cheat about the brlapi_error C token

◆ brlapi_gaierrno

#define brlapi_gaierrno   (brlapi_error.gaierrno)

Cheat about the brlapi_gaierrno C token

◆ brlapi_libcerrno

#define brlapi_libcerrno   (brlapi_error.libcerrno)

Cheat about the brlapi_libcerrno C token

Typedef Documentation

◆ brlapi__exceptionHandler_t

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

◆ brlapi_exceptionHandler_t

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
erroris a BRLAPI_ERROR_ error code;
typeis the type of the guilty packet;
packetpoints to the content of the guilty packet (might be a little bit truncated);
sizegives the guilty packet's size.

◆ brlapi_packetType_t

typedef uint32_t brlapi_packetType_t

Type for packet type. Only unsigned can cross networks, 32bits

Enumeration Type Documentation

◆ brlapi_error

BrlAPI Error codes

Enumerator
BRLAPI_ERROR_SUCCESS 

Success

BRLAPI_ERROR_SUCCESS 

Success

BRLAPI_ERROR_NOMEM 

Not enough memory

BRLAPI_ERROR_NOMEM 

Not enough memory

BRLAPI_ERROR_TTYBUSY 

A connection is already running in this tty

BRLAPI_ERROR_TTYBUSY 

A connection is already running in this tty

BRLAPI_ERROR_DEVICEBUSY 

A connection is already using RAW or suspend mode

BRLAPI_ERROR_DEVICEBUSY 

A connection is already using RAW or suspend mode

BRLAPI_ERROR_UNKNOWN_INSTRUCTION 

Not implemented in protocol

BRLAPI_ERROR_UNKNOWN_INSTRUCTION 

Not implemented in protocol

BRLAPI_ERROR_ILLEGAL_INSTRUCTION 

Forbiden in current mode

BRLAPI_ERROR_ILLEGAL_INSTRUCTION 

Forbiden in current mode

BRLAPI_ERROR_INVALID_PARAMETER 

Out of range or have no sense

BRLAPI_ERROR_INVALID_PARAMETER 

Out of range or have no sense

BRLAPI_ERROR_INVALID_PACKET 

Invalid size

BRLAPI_ERROR_INVALID_PACKET 

Invalid size

BRLAPI_ERROR_CONNREFUSED 

Connection refused

BRLAPI_ERROR_CONNREFUSED 

Connection refused

BRLAPI_ERROR_OPNOTSUPP 

Operation not supported

BRLAPI_ERROR_OPNOTSUPP 

Operation not supported

BRLAPI_ERROR_GAIERR 

Getaddrinfo error

BRLAPI_ERROR_GAIERR 

Getaddrinfo error

BRLAPI_ERROR_LIBCERR 

Libc error

BRLAPI_ERROR_LIBCERR 

Libc error

BRLAPI_ERROR_UNKNOWNTTY 

Couldn't find out the tty number

BRLAPI_ERROR_UNKNOWNTTY 

Couldn't find out the tty number

BRLAPI_ERROR_PROTOCOL_VERSION 

Bad protocol version

BRLAPI_ERROR_PROTOCOL_VERSION 

Bad protocol version

BRLAPI_ERROR_EOF 

Unexpected end of file

BRLAPI_ERROR_EOF 

Unexpected end of file

BRLAPI_ERROR_EMPTYKEY 

Key file empty

BRLAPI_ERROR_EMPTYKEY 

Key file empty

BRLAPI_ERROR_DRIVERERROR 

Packet returned by driver too large

BRLAPI_ERROR_DRIVERERROR 

Packet returned by driver too large

BRLAPI_ERROR_AUTHENTICATION 

Authentication failed

BRLAPI_ERROR_AUTHENTICATION 

Authentication failed

BRLAPI_ERROR_READONLY_PARAMETER 

Parameter can not be changed

BRLAPI_ERROR_READONLY_PARAMETER 

Parameter can not be changed

Function Documentation

◆ brlapi__defaultExceptionHandler()

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

◆ brlapi__setExceptionHandler()

brlapi__exceptionHandler_t BRLAPI_STDCALL brlapi__setExceptionHandler ( brlapi_handle_t handle,
brlapi__exceptionHandler_t  handler 
)

◆ brlapi__strexception()

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_defaultExceptionHandler()

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

◆ brlapi_error_location()

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

◆ brlapi_getPacketTypeName()

const char* BRLAPI_STDCALL brlapi_getPacketTypeName ( brlapi_packetType_t  type)

Get plain packet type

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

◆ brlapi_perror()

void BRLAPI_STDCALL brlapi_perror ( const char *  s)

Print a BrlAPI error message

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

◆ brlapi_setExceptionHandler()

brlapi_exceptionHandler_t BRLAPI_STDCALL brlapi_setExceptionHandler ( brlapi_exceptionHandler_t  handler)

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.

◆ brlapi_strerror()

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. Since the message is a constant string, the application must not free it. Also, this makes it unsafe in threaded environments, brlapi_strerror_r() should be used instead in that case.

◆ brlapi_strerror_r()

size_t BRLAPI_STDCALL brlapi_strerror_r ( const brlapi_error_t error,
char *  buf,
size_t  buflen 
)

Store plain error message

brlapi_strerror_r() stores the plain error message corresponding to its error argument. buflen has to be set to the size of buf, and brlapi_strerror_r() will store at most buflen bytes in buf. If buflen is not large enough for the whole error message, it will be truncated, but a trailing \0 character will still be set at buf[buflen-1].

Returns
the number of characters that should have been stored in buf (without the trailing \0 character). A value greater or equal to buflen thus means that the output was truncated.

If buflen is set to 0, buf can be set to NULL, and brlapi_strerror_r will thus only return the number of characters that would have been stored (without the trailing \0 character).

◆ brlapi_strexception()

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

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

◆ brlapi_errfun

const char* brlapi_errfun
extern

Shorthand for brlapi_error.errfun

◆ brlapi_errlist

const char* brlapi_errlist[]
extern

Error message list

These are the string constants used by brlapi_perror().

◆ brlapi_errno

enum brlapi_error brlapi_errno
extern

Shorthand for brlapi_error.errno

◆ brlapi_error

Global 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.

◆ brlapi_gaierrno

int brlapi_gaierrno
extern

Shorthand for brlapi_error.gaierrno

◆ brlapi_libcerrno

int brlapi_libcerrno
extern

Shorthand for brlapi_error.libcerrno

◆ brlapi_nerr

const int brlapi_nerr
extern

Number of error messages