1
.TH "Error handling" 3 "15 May 2009" "Version 1.0" "BrlAPI" \" -*- nroff -*-
5
Error handling \- How to handle errors.
12
.RI "struct \fBbrlapi_error_t\fP"
19
.RI "#define \fBBRLAPI_ERROR_SUCCESS\fP 0"
22
.RI "#define \fBBRLAPI_ERROR_NOMEM\fP 1"
25
.RI "#define \fBBRLAPI_ERROR_TTYBUSY\fP 2"
28
.RI "#define \fBBRLAPI_ERROR_DEVICEBUSY\fP 3"
31
.RI "#define \fBBRLAPI_ERROR_UNKNOWN_INSTRUCTION\fP 4"
34
.RI "#define \fBBRLAPI_ERROR_ILLEGAL_INSTRUCTION\fP 5"
37
.RI "#define \fBBRLAPI_ERROR_INVALID_PARAMETER\fP 6"
40
.RI "#define \fBBRLAPI_ERROR_INVALID_PACKET\fP 7"
43
.RI "#define \fBBRLAPI_ERROR_CONNREFUSED\fP 8"
46
.RI "#define \fBBRLAPI_ERROR_OPNOTSUPP\fP 9"
49
.RI "#define \fBBRLAPI_ERROR_GAIERR\fP 10"
52
.RI "#define \fBBRLAPI_ERROR_LIBCERR\fP 11"
55
.RI "#define \fBBRLAPI_ERROR_UNKNOWNTTY\fP 12"
58
.RI "#define \fBBRLAPI_ERROR_PROTOCOL_VERSION\fP 13"
61
.RI "#define \fBBRLAPI_ERROR_EOF\fP 14"
64
.RI "#define \fBBRLAPI_ERROR_EMPTYKEY\fP 15"
67
.RI "#define \fBBRLAPI_ERROR_DRIVERERROR\fP 16"
70
.RI "#define \fBBRLAPI_ERROR_AUTHENTICATION\fP 17"
73
.RI "#define \fBbrlapi_error\fP (*brlapi_error_location())"
76
.RI "#define \fBbrlapi_errno\fP (brlapi_error.brlerrno)"
79
.RI "#define \fBbrlapi_libcerrno\fP (brlapi_error.libcerrno)"
82
.RI "#define \fBbrlapi_gaierrno\fP (brlapi_error.gaierrno)"
85
.RI "#define \fBbrlapi_errfun\fP (brlapi_error.errfun)"
92
.RI "typedef uint32_t \fBbrlapi_packetType_t\fP"
95
.RI "typedef void(BRLAPI_STDCALL *) \fBbrlapi_exceptionHandler_t\fP (int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)"
98
.RI "typedef void(BRLAPI_STDCALL *) \fBbrlapi__exceptionHandler_t\fP (\fBbrlapi_handle_t\fP *handle, int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)"
105
.RI "void BRLAPI_STDCALL \fBbrlapi_perror\fP (const char *s)"
108
.RI "\fBbrlapi_error_t\fP *BRLAPI_STDCALL \fBbrlapi_error_location\fP (void)"
111
.RI "const char *BRLAPI_STDCALL \fBbrlapi_strerror\fP (const \fBbrlapi_error_t\fP *error)"
114
.RI "const char *BRLAPI_STDCALL \fBbrlapi_getPacketTypeName\fP (\fBbrlapi_packetType_t\fP type)"
117
.RI "int BRLAPI_STDCALL \fBbrlapi_strexception\fP (char *buffer, size_t bufferSize, int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t packetSize)"
120
.RI "int BRLAPI_STDCALL \fBbrlapi__strexception\fP (\fBbrlapi_handle_t\fP *handle, char *buffer, size_t bufferSize, int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t packetSize)"
123
.RI "\fBbrlapi_exceptionHandler_t\fP BRLAPI_STDCALL \fBbrlapi_setExceptionHandler\fP (\fBbrlapi_exceptionHandler_t\fP handler)"
126
.RI "\fBbrlapi__exceptionHandler_t\fP BRLAPI_STDCALL \fBbrlapi__setExceptionHandler\fP (\fBbrlapi_handle_t\fP *handle, \fBbrlapi__exceptionHandler_t\fP handler)"
129
.RI "void BRLAPI_STDCALL \fBbrlapi_defaultExceptionHandler\fP (int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)"
132
.RI "void BRLAPI_STDCALL \fBbrlapi__defaultExceptionHandler\fP (\fBbrlapi_handle_t\fP *handle, int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)"
139
.RI "const char * \fBbrlapi_errlist\fP []"
142
.RI "const int \fBbrlapi_nerr\fP"
145
.RI "\fBbrlapi_error_t\fP \fBbrlapi_error\fP"
148
.RI "int \fBbrlapi_errno\fP"
151
.RI "int \fBbrlapi_libcerrno\fP"
154
.RI "int \fBbrlapi_gaierrno\fP"
157
.RI "const char * \fBbrlapi_errfun\fP"
160
.SH "Detailed Description"
162
When a function fails, \fBbrlapi_errno\fP will hold an error code to explain why it failed. It should always be reported somehow.
164
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 \fIexception\fP handler. If the exception handler returns, the brlapi_something function will return an end-of-file error.
166
The default exception handler (\fBbrlapi_defaultExceptionHandler()\fP) dumps the guilty packet before abort()ing. It can be replaced by calling \fBbrlapi_setExceptionHandler()\fP. For instance, the Java and Python bindings use this for raising a Java or Python exception that may be caught.
167
.SH "Define Documentation"
169
.SS "#define \fBbrlapi_errfun\fP (brlapi_error.errfun)"
171
Cheat about the brlapi_errfun C token
172
.SS "#define \fBbrlapi_errno\fP (brlapi_error.brlerrno)"
174
Cheat about the brlapi_errno C token
175
.SS "#define \fBbrlapi_error\fP (*brlapi_error_location())"
177
Cheat about the brlapi_error C token
178
.SS "#define BRLAPI_ERROR_AUTHENTICATION 17"
180
Authentication failed
181
.SS "#define BRLAPI_ERROR_CONNREFUSED 8"
184
.SS "#define BRLAPI_ERROR_DEVICEBUSY 3"
186
A connection is already using RAW or suspend mode
187
.SS "#define BRLAPI_ERROR_DRIVERERROR 16"
189
Packet returned by driver too large
190
.SS "#define BRLAPI_ERROR_EMPTYKEY 15"
193
.SS "#define BRLAPI_ERROR_EOF 14"
195
Unexpected end of file
196
.SS "#define BRLAPI_ERROR_GAIERR 10"
199
.SS "#define BRLAPI_ERROR_ILLEGAL_INSTRUCTION 5"
201
Forbiden in current mode
202
.SS "#define BRLAPI_ERROR_INVALID_PACKET 7"
205
.SS "#define BRLAPI_ERROR_INVALID_PARAMETER 6"
207
Out of range or have no sense
208
.SS "#define BRLAPI_ERROR_LIBCERR 11"
211
.SS "#define BRLAPI_ERROR_NOMEM 1"
214
.SS "#define BRLAPI_ERROR_OPNOTSUPP 9"
216
Operation not supported
217
.SS "#define BRLAPI_ERROR_PROTOCOL_VERSION 13"
220
.SS "#define BRLAPI_ERROR_SUCCESS 0"
223
.SS "#define BRLAPI_ERROR_TTYBUSY 2"
225
A connection is already running in this tty
226
.SS "#define BRLAPI_ERROR_UNKNOWN_INSTRUCTION 4"
228
Not implemented in protocol
229
.SS "#define BRLAPI_ERROR_UNKNOWNTTY 12"
231
Couldn't find out the tty number
232
.SS "#define \fBbrlapi_gaierrno\fP (brlapi_error.gaierrno)"
234
Cheat about the brlapi_gaierrno C token
235
.SS "#define \fBbrlapi_libcerrno\fP (brlapi_error.libcerrno)"
237
Cheat about the brlapi_libcerrno C token
238
.SH "Typedef Documentation"
240
.SS "typedef void(BRLAPI_STDCALL *) \fBbrlapi__exceptionHandler_t\fP(\fBbrlapi_handle_t\fP *handle, int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)"
242
.SS "typedef void(BRLAPI_STDCALL *) \fBbrlapi_exceptionHandler_t\fP(int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)"
244
Types for exception handlers
246
Types of exception handlers which are to be given to \fBbrlapi_setExceptionHandler()\fP and \fBbrlapi__setExceptionHandler()\fP.
250
\fIhandle\fP is the handle corresponding to the guilty connection;
252
\fIerror\fP is a BRLAPI_ERROR_ error code;
254
\fItype\fP is the type of the guilty packet;
256
\fIpacket\fP points to the content of the guilty packet (might be a little bit truncated);
258
\fIsize\fP gives the guilty packet's size.
262
.SS "typedef uint32_t \fBbrlapi_packetType_t\fP"
264
Type for packet type. Only unsigned can cross networks, 32bits
265
.SH "Function Documentation"
267
.SS "void BRLAPI_STDCALL brlapi__defaultExceptionHandler (\fBbrlapi_handle_t\fP * handle, int error, \fBbrlapi_packetType_t\fP type, const void * packet, size_t size)"
269
.SS "\fBbrlapi__exceptionHandler_t\fP BRLAPI_STDCALL brlapi__setExceptionHandler (\fBbrlapi_handle_t\fP * handle, \fBbrlapi__exceptionHandler_t\fP handler)"
271
.SS "int BRLAPI_STDCALL brlapi__strexception (\fBbrlapi_handle_t\fP * handle, char * buffer, size_t bufferSize, int error, \fBbrlapi_packetType_t\fP type, const void * packet, size_t packetSize)"
273
.SS "void BRLAPI_STDCALL brlapi_defaultExceptionHandler (int error, \fBbrlapi_packetType_t\fP type, const void * packet, size_t size)"
275
.SS "\fBbrlapi_error_t\fP* BRLAPI_STDCALL brlapi_error_location (void)"
277
Get per-thread error location
279
In multithreaded software, \fBbrlapi_error\fP is thread-specific, so api.h cheats about the brlapi_error token and actually calls \fBbrlapi_error_location()\fP.
281
This gets the thread specific location of global variable \fBbrlapi_error\fP
282
.SS "const char* BRLAPI_STDCALL brlapi_getPacketTypeName (\fBbrlapi_packetType_t\fP type)"
284
Get plain packet type
286
\fBbrlapi_getPacketTypeName()\fP returns the plain packet type name corresponding to its argument.
287
.SS "void BRLAPI_STDCALL brlapi_perror (const char * s)"
289
Print a BrlAPI error message
291
\fBbrlapi_perror()\fP reads \fBbrlapi_error\fP, and acts just like perror().
292
.SS "\fBbrlapi_exceptionHandler_t\fP BRLAPI_STDCALL brlapi_setExceptionHandler (\fBbrlapi_exceptionHandler_t\fP handler)"
294
Set a new exception handler
296
\fBbrlapi_setExceptionHandler()\fP replaces the previous exception handler with the handler parameter. The previous exception handler is returned to make chaining error handlers possible.
298
The default handler just prints the exception and abort()s.
299
.SS "const char* BRLAPI_STDCALL brlapi_strerror (const \fBbrlapi_error_t\fP * error)"
301
Get plain error message
303
\fBbrlapi_strerror()\fP returns the plain error message corresponding to its argument.
304
.SS "int BRLAPI_STDCALL brlapi_strexception (char * buffer, size_t bufferSize, int error, \fBbrlapi_packetType_t\fP type, const void * packet, size_t packetSize)"
306
Describes an exception
308
\fBbrlapi_strexception()\fP puts a text describing the given exception in buffer.
310
The beginning of the guilty packet is dumped as a sequence of hex bytes.
314
the size of the text describing the exception, following snprintf()'s semantics.
318
.SH "Variable Documentation"
320
.SS "const char* \fBbrlapi_errfun\fP"
322
Shorthand for brlapi_error.errfun
323
.SS "const char* \fBbrlapi_errlist\fP[]"
327
These are the string constants used by \fBbrlapi_perror()\fP.
328
.SS "int \fBbrlapi_errno\fP"
330
Shorthand for brlapi_error.errno
331
.SS "\fBbrlapi_error_t\fP \fBbrlapi_error\fP"
333
Global variable brlapi_error
335
\fBbrlapi_error\fP is a global left-value containing the last error information. Its errno field is not reset to BRLAPI_ERROR_SUCCESS on success.
337
This information may be copied in \fBbrlapi_error_t\fP variables for later use with the brlapi_strerror function.
338
.SS "int \fBbrlapi_gaierrno\fP"
340
Shorthand for brlapi_error.gaierrno
341
.SS "int \fBbrlapi_libcerrno\fP"
343
Shorthand for brlapi_error.libcerrno
344
.SS "const int \fBbrlapi_nerr\fP"
346
Number of error messages
added
removed
Documents/BrlAPIref/man/man3/brlapi_error.3
