Provided by: libbrlapi-dev_6.5-5ubuntu3_amd64 
NAME
brlapi_error - Error handling
- How to handle errors.
SYNOPSIS
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_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)
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
#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_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
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_t
Type for packet type. Only unsigned can cross networks, 32bits
Enumeration Type Documentation
enum 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
void BRLAPI_STDCALL brlapi__defaultExceptionHandler (brlapi_handle_t * handle, int error,
brlapi_packetType_t type, const void * packet, size_t size)
brlapi__exceptionHandler_t BRLAPI_STDCALL brlapi__setExceptionHandler (brlapi_handle_t *
handle, brlapi__exceptionHandler_t handler)
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)
void BRLAPI_STDCALL brlapi_defaultExceptionHandler (int error, brlapi_packetType_t type, const
void * packet, size_t size)
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_t type)
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_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.
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.
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).
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
const char* brlapi_errfun [extern]
Shorthand for brlapi_error.errfun
const char* brlapi_errlist[] [extern]
Error message list
These are the string constants used by brlapi_perror().
enum brlapi_error brlapi_errno [extern]
Shorthand for brlapi_error.errno
brlapi_error_t brlapi_error [extern]
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.
int brlapi_gaierrno [extern]
Shorthand for brlapi_error.gaierrno
int brlapi_libcerrno [extern]
Shorthand for brlapi_error.libcerrno
const int brlapi_nerr [extern]
Number of error messages
Author
Generated automatically by Doxygen for BrlAPI from the source code.