brlapi_error - Error handling

Generated automatically by Doxygen for BrlAPI from the source code. BrlAPI Version 0.8 brlapi_error(3)

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.

enumbrlapi_error BrlAPI Error codes EnumeratorBRLAPI_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

voidBRLAPI_STDCALLbrlapi__defaultExceptionHandler(brlapi_handle_t*handle,interror,brlapi_packetType_ttype,constvoid*packet,size_tsize)brlapi__exceptionHandler_tBRLAPI_STDCALLbrlapi__setExceptionHandler(brlapi_handle_t*handle,brlapi__exceptionHandler_thandler)intBRLAPI_STDCALLbrlapi__strexception(brlapi_handle_t*handle,char*buffer,size_tbufferSize,interror,brlapi_packetType_ttype,constvoid*packet,size_tpacketSize)voidBRLAPI_STDCALLbrlapi_defaultExceptionHandler(interror,brlapi_packetType_ttype,constvoid*packet,size_tsize)brlapi_error_t*BRLAPI_STDCALLbrlapi_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_errorconstchar*BRLAPI_STDCALLbrlapi_getPacketTypeName(brlapi_packetType_ttype) Get plain packet type brlapi_getPacketTypeName() returns the plain packet type name corresponding to its argument. voidBRLAPI_STDCALLbrlapi_perror(constchar*s) Print a BrlAPI error message brlapi_perror() reads brlapi_error, and acts just like perror(). brlapi_exceptionHandler_tBRLAPI_STDCALLbrlapi_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. constchar*BRLAPI_STDCALLbrlapi_strerror(constbrlapi_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_tBRLAPI_STDCALLbrlapi_strerror_r(constbrlapi_error_t*error,char*buf,size_tbuflen) 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). intBRLAPI_STDCALLbrlapi_strexception(char*buffer,size_tbufferSize,interror,brlapi_packetType_ttype,constvoid*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.

#definebrlapi_errfun(brlapi_error.errfun) Cheat about the brlapi_errfun C token #definebrlapi_errno(brlapi_error.brlerrno) Cheat about the brlapi_errno C token #definebrlapi_error(*brlapi_error_location()) Cheat about the brlapi_error C token #definebrlapi_gaierrno(brlapi_error.gaierrno) Cheat about the brlapi_gaierrno C token #definebrlapi_libcerrno(brlapi_error.libcerrno) Cheat about the brlapi_libcerrno C token

brlapi_error - Error handling - How to handle errors.

DataStructures struct brlapi_error_tMacros #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_STDCALLbrlapi_perror (const char *s) brlapi_error_t *BRLAPI_STDCALLbrlapi_error_location (void) const char *BRLAPI_STDCALLbrlapi_strerror (const brlapi_error_t *error) size_t BRLAPI_STDCALLbrlapi_strerror_r (const brlapi_error_t *error, char *buf, size_t buflen) const char *BRLAPI_STDCALLbrlapi_getPacketTypeName (brlapi_packetType_t type) int BRLAPI_STDCALLbrlapi_strexception (char *buffer, size_t bufferSize, int error, brlapi_packetType_t type, const void *packet, size_t packetSize) int BRLAPI_STDCALLbrlapi__strexception (brlapi_handle_t *handle, char *buffer, size_t bufferSize, int error, brlapi_packetType_t type, const void *packet, size_t packetSize) brlapi_exceptionHandler_tBRLAPI_STDCALLbrlapi_setExceptionHandler (brlapi_exceptionHandler_t handler) brlapi__exceptionHandler_tBRLAPI_STDCALLbrlapi__setExceptionHandler (brlapi_handle_t *handle, brlapi__exceptionHandler_t handler) void BRLAPI_STDCALLbrlapi_defaultExceptionHandler (int error, brlapi_packetType_t type, const void *packet, size_t size) void BRLAPI_STDCALLbrlapi__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_nerrbrlapi_error_tbrlapi_error enum brlapi_errorbrlapi_errno int brlapi_libcerrno int brlapi_gaierrno const char * brlapi_errfun

typedefvoid(BRLAPI_STDCALL*brlapi__exceptionHandler_t)(brlapi_handle_t*handle,interror,brlapi_packetType_ttype,constvoid*packet,size_tsize)typedefvoid(BRLAPI_STDCALL*brlapi_exceptionHandler_t)(interror,brlapi_packetType_ttype,constvoid*packet,size_tsize) Types for exception handlers Types of exception handlers which are to be given to brlapi_setExceptionHandler() and brlapi__setExceptionHandler(). Parameterserror 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. typedefuint32_tbrlapi_packetType_t Type for packet type. Only unsigned can cross networks, 32bits

constchar*brlapi_errfun[extern] Shorthand for brlapi_error.errfun constchar*brlapi_errlist[][extern] Error message list These are the string constants used by brlapi_perror(). enumbrlapi_errorbrlapi_errno[extern] Shorthand for brlapi_error.errno brlapi_error_tbrlapi_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. intbrlapi_gaierrno[extern] Shorthand for brlapi_error.gaierrno intbrlapi_libcerrno[extern] Shorthand for brlapi_error.libcerrno constintbrlapi_nerr[extern] Number of error messages