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 (*brlapi_error_location())
31 #define brlapi_errno (brlapi_error.brlerrno)
32 #define brlapi_libcerrno (brlapi_error.libcerrno)
33 #define brlapi_gaierrno (brlapi_error.gaierrno)
34 #define brlapi_errfun (brlapi_error.errfun)
35 Typedefs
37 typedef uint32_t brlapi_packetType_t
38 typedef void(BRLAPI_STDCALL * brlapi_exceptionHandler_t )(int error,
39 brlapi_packetType_t type, const void *packet, size_t size)
40 typedef void(BRLAPI_STDCALL * brlapi__exceptionHandler_t
41 )(brlapi_handle_t *handle, int error, brlapi_packetType_t type,
42 const void *packet, size_t size)
43 Functions
45 void BRLAPI_STDCALL brlapi_perror (const char *s)
46 brlapi_error_t *BRLAPI_STDCALL brlapi_error_location (void)
47 const char *BRLAPI_STDCALL brlapi_strerror (const brlapi_error_t
48 *error)
49 const char *BRLAPI_STDCALL brlapi_getPacketTypeName
50 (brlapi_packetType_t type)
51 int BRLAPI_STDCALL brlapi_strexception (char *buffer, size_t
52 bufferSize, int error, brlapi_packetType_t type, const void
53 *packet, size_t packetSize)
54 int BRLAPI_STDCALL brlapi__strexception (brlapi_handle_t *handle, char
55 *buffer, size_t bufferSize, int error, brlapi_packetType_t type,
56 const void *packet, size_t packetSize)
57 brlapi_exceptionHandler_t BRLAPI_STDCALL brlapi_setExceptionHandler
58 (brlapi_exceptionHandler_t handler)
59 brlapi__exceptionHandler_t BRLAPI_STDCALL brlapi__setExceptionHandler
60 (brlapi_handle_t *handle, brlapi__exceptionHandler_t handler)
61 void BRLAPI_STDCALL brlapi_defaultExceptionHandler (int error,
62 brlapi_packetType_t type, const void *packet, size_t size)
63 void BRLAPI_STDCALL brlapi__defaultExceptionHandler (brlapi_handle_t
64 *handle, int error, brlapi_packetType_t type, const void *packet,
65 size_t size)
66 Variables
68 const char * brlapi_errlist []
69 const int brlapi_nerr
70 brlapi_error_t brlapi_error
71 int brlapi_errno
72 int brlapi_libcerrno
73 int brlapi_gaierrno
74 const char * brlapi_errfun
75
77 When a function fails, brlapi_errno will hold an error code to explain
78 why it failed. It should always be reported somehow.
79 Although most errors are reported that way, some (called exceptions)
81 are reported asynchronously for efficiency reasons, because they always
82 just report a programming error. The affected functions are:
83 brlapi_setFocus, brlapi_write* and brlapi_sendRaw. When they happen,
84 the next call to brlapi_something will close the connection and call
85 the exception handler. If the exception handler returns, the
86 brlapi_something function will return an end-of-file error.
87 The default exception handler (brlapi_defaultExceptionHandler()) dumps
89 the guilty packet before abort()ing. It can be replaced by calling
90 brlapi_setExceptionHandler(). For instance, the Java and Python
91 bindings use this for raising a Java or Python exception that may be
92 caught.
93
95 #define brlapi_errfun (brlapi_error.errfun)
96 Cheat about the brlapi_errfun C token
97 #define brlapi_errno (brlapi_error.brlerrno)
99 Cheat about the brlapi_errno C token
100 #define brlapi_error (*brlapi_error_location())
102 Cheat about the brlapi_error C token
103 #define BRLAPI_ERROR_CONNREFUSED 8
105 Connection refused
106 #define BRLAPI_ERROR_DEVICEBUSY 3
108 A connection is already using RAW or suspend mode
109 #define BRLAPI_ERROR_DRIVERERROR 16
111 Packet returned by driver too large
112 #define BRLAPI_ERROR_EMPTYKEY 15
114 Key file empty
115 #define BRLAPI_ERROR_EOF 14
117 Unexpected end of file
118 #define BRLAPI_ERROR_GAIERR 10
120 Getaddrinfo error
121 #define BRLAPI_ERROR_ILLEGAL_INSTRUCTION 5
123 Forbiden in current mode
124 #define BRLAPI_ERROR_INVALID_PACKET 7
126 Invalid size
127 #define BRLAPI_ERROR_INVALID_PARAMETER 6
129 Out of range or have no sense
130 #define BRLAPI_ERROR_LIBCERR 11
132 Libc error
133 #define BRLAPI_ERROR_NOMEM 1
135 Not enough memory
136 #define BRLAPI_ERROR_OPNOTSUPP 9
138 Operation not supported
139 #define BRLAPI_ERROR_PROTOCOL_VERSION 13
141 Bad protocol version
142 #define BRLAPI_ERROR_SUCCESS 0
144 Success
145 #define BRLAPI_ERROR_TTYBUSY 2
147 A connection is already running in this tty
148 #define BRLAPI_ERROR_UNKNOWN_INSTRUCTION 4
150 Not implemented in protocol
151 #define BRLAPI_ERROR_UNKNOWNTTY 12
153 Couldn't find out the tty number
154 #define brlapi_gaierrno (brlapi_error.gaierrno)
156 Cheat about the brlapi_gaierrno C token
157 #define brlapi_libcerrno (brlapi_error.libcerrno)
159 Cheat about the brlapi_libcerrno C token
160
162 typedef void(BRLAPI_STDCALL * brlapi__exceptionHandler_t)(brlapi_handle_t
163 *handle, int error, brlapi_packetType_t type, const void *packet,
164 size_t size)
165 typedef void(BRLAPI_STDCALL * brlapi_exceptionHandler_t)(int error,
166 brlapi_packetType_t type, const void *packet, size_t size)
167 Types for exception handlers
168 Types of exception handlers which are to be given to
170 brlapi_setExceptionHandler() and brlapi__setExceptionHandler().
171 Parameters:
173 handle is the handle corresponding to the guilty connection;
174 error is a BRLERR_ error code;
175 type is the type of the guilty packet;
176 packet points to the content of the guilty packet (might be a
177 little bit truncated);
178 size gives the guilty packet's size.
179 typedef uint32_t brlapi_packetType_t
181 Type for packet type. Only unsigned can cross networks, 32bits
182
184 void BRLAPI_STDCALL brlapi__defaultExceptionHandler (brlapi_handle_t *
185 handle, int error, brlapi_packetType_t type, const void * packet,
186 size_t size)
187 brlapi__exceptionHandler_t BRLAPI_STDCALL brlapi__setExceptionHandler
188 (brlapi_handle_t * handle, brlapi__exceptionHandler_t handler)
189 int BRLAPI_STDCALL brlapi__strexception (brlapi_handle_t * handle, char *
190 buffer, size_t bufferSize, int error, brlapi_packetType_t type, const
191 void * packet, size_t packetSize)
192 void BRLAPI_STDCALL brlapi_defaultExceptionHandler (int error,
193 brlapi_packetType_t type, const void * packet, size_t size)
194 brlapi_error_t* BRLAPI_STDCALL brlapi_error_location (void)
195 Get per-thread error location
196 In multithreaded software, brlapi_error is thread-specific, so api.h
198 cheats about the brlapi_error token and actually calls
199 brlapi_error_location().
200 This gets the thread specific location of global variable brlapi_error
202 const char* BRLAPI_STDCALL brlapi_getPacketTypeName (brlapi_packetType_t
204 type)
205 Get plain packet type
206 brlapi_getPacketTypeName() returns the plain packet type name
208 corresponding to its argument.
209 void BRLAPI_STDCALL brlapi_perror (const char * s)
211 Print a BrlAPI error message
212 brlapi_perror() reads brlapi_error, and acts just like perror().
214 brlapi_exceptionHandler_t BRLAPI_STDCALL brlapi_setExceptionHandler
216 (brlapi_exceptionHandler_t handler)
217 Set a new exception handler
218 brlapi_setExceptionHandler() replaces the previous exception handler
220 with the handler parameter. The previous exception handler is returned
221 to make chaining error handlers possible.
222 The default handler just prints the exception and abort()s.
224 const char* BRLAPI_STDCALL brlapi_strerror (const brlapi_error_t * error)
226 Get plain error message
227 brlapi_strerror() returns the plain error message corresponding to its
229 argument.
230 int BRLAPI_STDCALL brlapi_strexception (char * buffer, size_t bufferSize,
232 int error, brlapi_packetType_t type, const void * packet, size_t
233 packetSize)
234 Describes an exception
235 brlapi_strexception() puts a text describing the given exception in
237 buffer.
238 The beginning of the guilty packet is dumped as a sequence of hex
240 bytes.
241 Returns:
243 the size of the text describing the exception, following
244 snprintf()'s semantics.
245
247 const char* brlapi_errfun
248 Shorthand for brlapi_error.errfun
249 const char* brlapi_errlist[]
251 Error message list
252 These are the string constants used by brlapi_perror().
254 int brlapi_errno
256 Shorthand for brlapi_error.errno
257 brlapi_error_t brlapi_error
259 Global variable brlapi_error
260 brlapi_error is a global left-value containing the last error
262 information. Its errno field is not reset to BRLERR_SUCCESS on success.
263 This information may be copied in brlapi_error_t variables for later
265 use with the brlapi_strerror function.
266 int brlapi_gaierrno
268 Shorthand for brlapi_error.gaierrno
269 int brlapi_libcerrno
271 Shorthand for brlapi_error.libcerrno
272 const int brlapi_nerr
274 Number of error messages
275Version 1.0 4 Jun 2007 Error handling(3)