Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

brlapi_perror (3)

Name

brlapi_perror - Error handling - How to handle errors.

Synopsis

Data Structures
struct brlapi_error_t

Macros
#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

Description

brlapi_error(3)                     BrlAPI                     brlapi_error(3)



NAME
       brlapi_error - Error handling

        - How to handle errors.


SYNOPSIS
   Data Structures
       struct brlapi_error_t

   Macros
       #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.

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_ERROR_AUTHENTICATION   17
       Authentication failed

   #define BRLAPI_ERROR_CONNREFUSED   8
       Connection refused

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

   #define BRLAPI_ERROR_DRIVERERROR   16
       Packet returned by driver too large

   #define BRLAPI_ERROR_EMPTYKEY   15
       Key file empty

   #define BRLAPI_ERROR_EOF   14
       Unexpected end of file

   #define BRLAPI_ERROR_GAIERR   10
       Getaddrinfo error

   #define BRLAPI_ERROR_ILLEGAL_INSTRUCTION   5
       Forbiden in current mode

   #define BRLAPI_ERROR_INVALID_PACKET   7
       Invalid size

   #define BRLAPI_ERROR_INVALID_PARAMETER   6
       Out of range or have no sense

   #define BRLAPI_ERROR_LIBCERR   11
       Libc error

   #define BRLAPI_ERROR_NOMEM   1
       Not enough memory

   #define BRLAPI_ERROR_OPNOTSUPP   9
       Operation not supported

   #define BRLAPI_ERROR_PROTOCOL_VERSION   13
       Bad protocol version

   #define BRLAPI_ERROR_SUCCESS   0
       Success

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

   #define BRLAPI_ERROR_UNKNOWN_INSTRUCTION   4
       Not implemented in protocol

   #define BRLAPI_ERROR_UNKNOWNTTY   12
       Couldn'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_t
       Type for packet type. Only unsigned can cross networks, 32bits

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.

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

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



ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------------------+
       |ATTRIBUTE TYPE |       ATTRIBUTE VALUE        |
       +---------------+------------------------------+
       |Availability   | library/accessibility/brltty |
       +---------------+------------------------------+
       |Stability      | Pass-through volatile        |
       +---------------+------------------------------+

NOTES
       Source code for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This software was built from source available at
       https://github.com/oracle/solaris-userland.  The original community
       source was downloaded from
       http://mielke.cc/brltty//archive/brltty-6.0.tar.xz.

       Further information about this software can be found on the open source
       community website at http://mielke.cc/brltty/.



Version 0.7                     Mon Jun 27 2022                brlapi_error(3)