1Error handling(3) BrlAPI Error handling(3)
2
6 Error handling - How to handle errors.
7 Data Structures
10 struct brlapi_error_t
11 Defines
13 #define BRLAPI_ERROR_SUCCESS 0
14 #define BRLAPI_ERROR_NOMEM 1
15 #define BRLAPI_ERROR_TTYBUSY 2
16 #define BRLAPI_ERROR_DEVICEBUSY 3
17 #define BRLAPI_ERROR_UNKNOWN_INSTRUCTION 4
18 #define BRLAPI_ERROR_ILLEGAL_INSTRUCTION 5
19 #define BRLAPI_ERROR_INVALID_PARAMETER 6
20 #define BRLAPI_ERROR_INVALID_PACKET 7
21 #define BRLAPI_ERROR_CONNREFUSED 8
22 #define BRLAPI_ERROR_OPNOTSUPP 9
23 #define BRLAPI_ERROR_GAIERR 10
24 #define BRLAPI_ERROR_LIBCERR 11
25 #define BRLAPI_ERROR_UNKNOWNTTY 12
26 #define BRLAPI_ERROR_PROTOCOL_VERSION 13
27 #define BRLAPI_ERROR_EOF 14
28 #define BRLAPI_ERROR_EMPTYKEY 15
29 #define BRLAPI_ERROR_DRIVERERROR 16
30 #define BRLAPI_ERROR_AUTHENTICATION 17
31 #define brlapi_error (*brlapi_error_location())
32 #define brlapi_errno (brlapi_error.brlerrno)
33 #define brlapi_libcerrno (brlapi_error.libcerrno)
34 #define brlapi_gaierrno (brlapi_error.gaierrno)
35 #define brlapi_errfun (brlapi_error.errfun)
36 Typedefs
38 typedef uint32_t brlapi_packetType_t
39 typedef void(BRLAPI_STDCALL * brlapi_exceptionHandler_t )(int error,
40 brlapi_packetType_t type, const void *packet, size_t size)
41 typedef void(BRLAPI_STDCALL * brlapi__exceptionHandler_t
42 )(brlapi_handle_t *handle, int error, brlapi_packetType_t type,
43 const void *packet, size_t size)
44 Functions
46 void BRLAPI_STDCALL brlapi_perror (const char *s)
47 brlapi_error_t *BRLAPI_STDCALL brlapi_error_location (void)
48 const char *BRLAPI_STDCALL brlapi_strerror (const brlapi_error_t
49 *error)
50 const char *BRLAPI_STDCALL brlapi_getPacketTypeName
51 (brlapi_packetType_t type)
52 int BRLAPI_STDCALL brlapi_strexception (char *buffer, size_t
53 bufferSize, int error, brlapi_packetType_t type, const void
54 *packet, size_t packetSize)
55 int BRLAPI_STDCALL brlapi__strexception (brlapi_handle_t *handle, char
56 *buffer, size_t bufferSize, int error, brlapi_packetType_t type,
57 const void *packet, size_t packetSize)
58 brlapi_exceptionHandler_t BRLAPI_STDCALL brlapi_setExceptionHandler
59 (brlapi_exceptionHandler_t handler)
60 brlapi__exceptionHandler_t BRLAPI_STDCALL brlapi__setExceptionHandler
61 (brlapi_handle_t *handle, brlapi__exceptionHandler_t handler)
62 void BRLAPI_STDCALL brlapi_defaultExceptionHandler (int error,
63 brlapi_packetType_t type, const void *packet, size_t size)
64 void BRLAPI_STDCALL brlapi__defaultExceptionHandler (brlapi_handle_t
65 *handle, int error, brlapi_packetType_t type, const void *packet,
66 size_t size)
67 Variables
69 const char * brlapi_errlist []
70 const int brlapi_nerr
71 brlapi_error_t brlapi_error
72 int brlapi_errno
73 int brlapi_libcerrno
74 int brlapi_gaierrno
75 const char * brlapi_errfun
76
78 When a function fails, brlapi_errno will hold an error code to explain
79 why it failed. It should always be reported somehow.
80 Although most errors are reported that way, some (called exceptions)
82 are reported asynchronously for efficiency reasons, because they always
83 just report a programming error. The affected functions are:
84 brlapi_setFocus, brlapi_write* and brlapi_sendRaw. When they happen,
85 the next call to brlapi_something will close the connection and call
86 the exception handler. If the exception handler returns, the
87 brlapi_something function will return an end-of-file error.
88 The default exception handler (brlapi_defaultExceptionHandler()) dumps
90 the guilty packet before abort()ing. It can be replaced by calling
91 brlapi_setExceptionHandler(). For instance, the Java and Python
92 bindings use this for raising a Java or Python exception that may be
93 caught.
94
96 #define brlapi_errfun (brlapi_error.errfun)
97 Cheat about the brlapi_errfun C token
98 #define brlapi_errno (brlapi_error.brlerrno)
100 Cheat about the brlapi_errno C token
101 #define brlapi_error (*brlapi_error_location())
103 Cheat about the brlapi_error C token
104 #define BRLAPI_ERROR_AUTHENTICATION 17
106 Authentication failed
107 #define BRLAPI_ERROR_CONNREFUSED 8
109 Connection refused
110 #define BRLAPI_ERROR_DEVICEBUSY 3
112 A connection is already using RAW or suspend mode
113 #define BRLAPI_ERROR_DRIVERERROR 16
115 Packet returned by driver too large
116 #define BRLAPI_ERROR_EMPTYKEY 15
118 Key file empty
119 #define BRLAPI_ERROR_EOF 14
121 Unexpected end of file
122 #define BRLAPI_ERROR_GAIERR 10
124 Getaddrinfo error
125 #define BRLAPI_ERROR_ILLEGAL_INSTRUCTION 5
127 Forbiden in current mode
128 #define BRLAPI_ERROR_INVALID_PACKET 7
130 Invalid size
131 #define BRLAPI_ERROR_INVALID_PARAMETER 6
133 Out of range or have no sense
134 #define BRLAPI_ERROR_LIBCERR 11
136 Libc error
137 #define BRLAPI_ERROR_NOMEM 1
139 Not enough memory
140 #define BRLAPI_ERROR_OPNOTSUPP 9
142 Operation not supported
143 #define BRLAPI_ERROR_PROTOCOL_VERSION 13
145 Bad protocol version
146 #define BRLAPI_ERROR_SUCCESS 0
148 Success
149 #define BRLAPI_ERROR_TTYBUSY 2
151 A connection is already running in this tty
152 #define BRLAPI_ERROR_UNKNOWN_INSTRUCTION 4
154 Not implemented in protocol
155 #define BRLAPI_ERROR_UNKNOWNTTY 12
157 Couldn't find out the tty number
158 #define brlapi_gaierrno (brlapi_error.gaierrno)
160 Cheat about the brlapi_gaierrno C token
161 #define brlapi_libcerrno (brlapi_error.libcerrno)
163 Cheat about the brlapi_libcerrno C token
164
166 typedef void(BRLAPI_STDCALL * brlapi__exceptionHandler_t)(brlapi_handle_t
167 *handle, int error, brlapi_packetType_t type, const void *packet,
168 size_t size)
169 typedef void(BRLAPI_STDCALL * brlapi_exceptionHandler_t)(int error,
170 brlapi_packetType_t type, const void *packet, size_t size)
171 Types for exception handlers
172 Types of exception handlers which are to be given to
174 brlapi_setExceptionHandler() and brlapi__setExceptionHandler().
175 Parameters:
177 handle is the handle corresponding to the guilty connection;
178 error is a BRLAPI_ERROR_ error code;
179 type is the type of the guilty packet;
180 packet points to the content of the guilty packet (might be a
181 little bit truncated);
182 size gives the guilty packet's size.
183 typedef uint32_t brlapi_packetType_t
185 Type for packet type. Only unsigned can cross networks, 32bits
186
188 void BRLAPI_STDCALL brlapi__defaultExceptionHandler (brlapi_handle_t *
189 handle, int error, brlapi_packetType_t type, const void * packet,
190 size_t size)
191 brlapi__exceptionHandler_t BRLAPI_STDCALL brlapi__setExceptionHandler
192 (brlapi_handle_t * handle, brlapi__exceptionHandler_t handler)
193 int BRLAPI_STDCALL brlapi__strexception (brlapi_handle_t * handle, char *
194 buffer, size_t bufferSize, int error, brlapi_packetType_t type, const
195 void * packet, size_t packetSize)
196 void BRLAPI_STDCALL brlapi_defaultExceptionHandler (int error,
197 brlapi_packetType_t type, const void * packet, size_t size)
198 brlapi_error_t* BRLAPI_STDCALL brlapi_error_location (void)
199 Get per-thread error location
200 In multithreaded software, brlapi_error is thread-specific, so api.h
202 cheats about the brlapi_error token and actually calls
203 brlapi_error_location().
204 This gets the thread specific location of global variable brlapi_error
206 const char* BRLAPI_STDCALL brlapi_getPacketTypeName (brlapi_packetType_t
208 type)
209 Get plain packet type
210 brlapi_getPacketTypeName() returns the plain packet type name
212 corresponding to its argument.
213 void BRLAPI_STDCALL brlapi_perror (const char * s)
215 Print a BrlAPI error message
216 brlapi_perror() reads brlapi_error, and acts just like perror().
218 brlapi_exceptionHandler_t BRLAPI_STDCALL brlapi_setExceptionHandler
220 (brlapi_exceptionHandler_t handler)
221 Set a new exception handler
222 brlapi_setExceptionHandler() replaces the previous exception handler
224 with the handler parameter. The previous exception handler is returned
225 to make chaining error handlers possible.
226 The default handler just prints the exception and abort()s.
228 const char* BRLAPI_STDCALL brlapi_strerror (const brlapi_error_t * error)
230 Get plain error message
231 brlapi_strerror() returns the plain error message corresponding to its
233 argument.
234 int BRLAPI_STDCALL brlapi_strexception (char * buffer, size_t bufferSize,
236 int error, brlapi_packetType_t type, const void * packet, size_t
237 packetSize)
238 Describes an exception
239 brlapi_strexception() puts a text describing the given exception in
241 buffer.
242 The beginning of the guilty packet is dumped as a sequence of hex
244 bytes.
245 Returns:
247 the size of the text describing the exception, following
248 snprintf()'s semantics.
249
251 const char* brlapi_errfun
252 Shorthand for brlapi_error.errfun
253 const char* brlapi_errlist[]
255 Error message list
256 These are the string constants used by brlapi_perror().
258 int brlapi_errno
260 Shorthand for brlapi_error.errno
261 brlapi_error_t brlapi_error
263 Global variable brlapi_error
264 brlapi_error is a global left-value containing the last error
266 information. Its errno field is not reset to BRLAPI_ERROR_SUCCESS on
267 success.
268 This information may be copied in brlapi_error_t variables for later
270 use with the brlapi_strerror function.
271 int brlapi_gaierrno
273 Shorthand for brlapi_error.gaierrno
274 int brlapi_libcerrno
276 Shorthand for brlapi_error.libcerrno
277 const int brlapi_nerr
279 Number of error messages
280Version 1.0 7 Oct 2009 Error handling(3)