.TH "brlapi_error" 3 "Version 0.8" "BrlAPI" \" -*- nroff -*- .ad l .nh .SH NAME brlapi_error \- Error handling .PP \- How to handle errors\&. .SH SYNOPSIS .br .PP .SS "Data Structures" .in +1c .ti -1c .RI "struct \fBbrlapi_error_t\fP" .br .in -1c .SS "Macros" .in +1c .ti -1c .RI "#define \fBbrlapi_error\fP (*\fBbrlapi_error_location\fP())" .br .ti -1c .RI "#define \fBbrlapi_errno\fP (brlapi_error\&.brlerrno)" .br .ti -1c .RI "#define \fBbrlapi_libcerrno\fP (brlapi_error\&.libcerrno)" .br .ti -1c .RI "#define \fBbrlapi_gaierrno\fP (brlapi_error\&.gaierrno)" .br .ti -1c .RI "#define \fBbrlapi_errfun\fP (brlapi_error\&.errfun)" .br .in -1c .SS "Typedefs" .in +1c .ti -1c .RI "typedef uint32_t \fBbrlapi_packetType_t\fP" .br .ti -1c .RI "typedef void(\fBBRLAPI_STDCALL\fP * \fBbrlapi_exceptionHandler_t\fP) (int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)" .br .ti -1c .RI "typedef void(\fBBRLAPI_STDCALL\fP * \fBbrlapi__exceptionHandler_t\fP) (\fBbrlapi_handle_t\fP *handle, int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)" .br .in -1c .SS "Enumerations" .in +1c .ti -1c .RI "enum \fBbrlapi_error\fP { \fBBRLAPI_ERROR_SUCCESS\fP = 0, \fBBRLAPI_ERROR_SUCCESS\fP = 0, \fBBRLAPI_ERROR_NOMEM\fP = 1, \fBBRLAPI_ERROR_NOMEM\fP = 1, \fBBRLAPI_ERROR_TTYBUSY\fP = 2, \fBBRLAPI_ERROR_TTYBUSY\fP = 2, \fBBRLAPI_ERROR_DEVICEBUSY\fP = 3, \fBBRLAPI_ERROR_DEVICEBUSY\fP = 3, \fBBRLAPI_ERROR_UNKNOWN_INSTRUCTION\fP = 4, \fBBRLAPI_ERROR_UNKNOWN_INSTRUCTION\fP = 4, \fBBRLAPI_ERROR_ILLEGAL_INSTRUCTION\fP = 5, \fBBRLAPI_ERROR_ILLEGAL_INSTRUCTION\fP = 5, \fBBRLAPI_ERROR_INVALID_PARAMETER\fP = 6, \fBBRLAPI_ERROR_INVALID_PARAMETER\fP = 6, \fBBRLAPI_ERROR_INVALID_PACKET\fP = 7, \fBBRLAPI_ERROR_INVALID_PACKET\fP = 7, \fBBRLAPI_ERROR_CONNREFUSED\fP = 8, \fBBRLAPI_ERROR_CONNREFUSED\fP = 8, \fBBRLAPI_ERROR_OPNOTSUPP\fP = 9, \fBBRLAPI_ERROR_OPNOTSUPP\fP = 9, \fBBRLAPI_ERROR_GAIERR\fP = 10, \fBBRLAPI_ERROR_GAIERR\fP = 10, \fBBRLAPI_ERROR_LIBCERR\fP = 11, \fBBRLAPI_ERROR_LIBCERR\fP = 11, \fBBRLAPI_ERROR_UNKNOWNTTY\fP = 12, \fBBRLAPI_ERROR_UNKNOWNTTY\fP = 12, \fBBRLAPI_ERROR_PROTOCOL_VERSION\fP = 13, \fBBRLAPI_ERROR_PROTOCOL_VERSION\fP = 13, \fBBRLAPI_ERROR_EOF\fP = 14, \fBBRLAPI_ERROR_EOF\fP = 14, \fBBRLAPI_ERROR_EMPTYKEY\fP = 15, \fBBRLAPI_ERROR_EMPTYKEY\fP = 15, \fBBRLAPI_ERROR_DRIVERERROR\fP = 16, \fBBRLAPI_ERROR_DRIVERERROR\fP = 16, \fBBRLAPI_ERROR_AUTHENTICATION\fP = 17, \fBBRLAPI_ERROR_AUTHENTICATION\fP = 17, \fBBRLAPI_ERROR_READONLY_PARAMETER\fP = 18, \fBBRLAPI_ERROR_READONLY_PARAMETER\fP = 18 }" .br .in -1c .SS "Functions" .in +1c .ti -1c .RI "void \fBBRLAPI_STDCALL\fP \fBbrlapi_perror\fP (const char *s)" .br .ti -1c .RI "\fBbrlapi_error_t\fP *\fBBRLAPI_STDCALL\fP \fBbrlapi_error_location\fP (void)" .br .ti -1c .RI "const char *\fBBRLAPI_STDCALL\fP \fBbrlapi_strerror\fP (const \fBbrlapi_error_t\fP *error)" .br .ti -1c .RI "size_t \fBBRLAPI_STDCALL\fP \fBbrlapi_strerror_r\fP (const \fBbrlapi_error_t\fP *error, char *buf, size_t buflen)" .br .ti -1c .RI "const char *\fBBRLAPI_STDCALL\fP \fBbrlapi_getPacketTypeName\fP (\fBbrlapi_packetType_t\fP type)" .br .ti -1c .RI "int \fBBRLAPI_STDCALL\fP \fBbrlapi_strexception\fP (char *buffer, size_t bufferSize, int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t packetSize)" .br .ti -1c .RI "int \fBBRLAPI_STDCALL\fP \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)" .br .ti -1c .RI "\fBbrlapi_exceptionHandler_t\fP \fBBRLAPI_STDCALL\fP \fBbrlapi_setExceptionHandler\fP (\fBbrlapi_exceptionHandler_t\fP handler)" .br .ti -1c .RI "\fBbrlapi__exceptionHandler_t\fP \fBBRLAPI_STDCALL\fP \fBbrlapi__setExceptionHandler\fP (\fBbrlapi_handle_t\fP *handle, \fBbrlapi__exceptionHandler_t\fP handler)" .br .ti -1c .RI "void \fBBRLAPI_STDCALL\fP \fBbrlapi_defaultExceptionHandler\fP (int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)" .br .ti -1c .RI "void \fBBRLAPI_STDCALL\fP \fBbrlapi__defaultExceptionHandler\fP (\fBbrlapi_handle_t\fP *handle, int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)" .br .in -1c .SS "Variables" .in +1c .ti -1c .RI "const char * \fBbrlapi_errlist\fP []" .br .ti -1c .RI "const int \fBbrlapi_nerr\fP" .br .ti -1c .RI "\fBbrlapi_error_t\fP \fBbrlapi_error\fP" .br .ti -1c .RI "enum \fBbrlapi_error\fP \fBbrlapi_errno\fP" .br .ti -1c .RI "int \fBbrlapi_libcerrno\fP" .br .ti -1c .RI "int \fBbrlapi_gaierrno\fP" .br .ti -1c .RI "const char * \fBbrlapi_errfun\fP" .br .in -1c .SH "Detailed Description" .PP When a function fails, \fBbrlapi_errno\fP will hold an error code to explain why it failed\&. It should always be reported somehow\&. .PP 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\&. .PP 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\&. .SH "Macro Definition Documentation" .PP .SS "#define brlapi_errfun (brlapi_error\&.errfun)" Cheat about the brlapi_errfun C token .SS "#define brlapi_errno (brlapi_error\&.brlerrno)" Cheat about the brlapi_errno C token .SS "#define \fBbrlapi_error\fP (*\fBbrlapi_error_location\fP())" Cheat about the brlapi_error C token .SS "#define brlapi_gaierrno (brlapi_error\&.gaierrno)" Cheat about the brlapi_gaierrno C token .SS "#define brlapi_libcerrno (brlapi_error\&.libcerrno)" Cheat about the brlapi_libcerrno C token .SH "Typedef Documentation" .PP .SS "typedef void(\fBBRLAPI_STDCALL\fP * brlapi__exceptionHandler_t) (\fBbrlapi_handle_t\fP *handle, int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)" .SS "typedef void(\fBBRLAPI_STDCALL\fP * brlapi_exceptionHandler_t) (int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)" Types for exception handlers .PP Types of exception handlers which are to be given to \fBbrlapi_setExceptionHandler()\fP and \fBbrlapi__setExceptionHandler()\fP\&. .PP \fBParameters\fP .RS 4 \fIerror\fP is a BRLAPI_ERROR_ error code; .br \fItype\fP is the type of the guilty packet; .br \fIpacket\fP points to the content of the guilty packet (might be a little bit truncated); .br \fIsize\fP gives the guilty packet's size\&. .RE .PP .SS "typedef uint32_t \fBbrlapi_packetType_t\fP" Type for packet type\&. Only unsigned can cross networks, 32bits .SH "Enumeration Type Documentation" .PP .SS "enum \fBbrlapi_error\fP" BrlAPI Error codes .PP \fBEnumerator\fP .in +1c .TP \fB\fIBRLAPI_ERROR_SUCCESS \fP\fP Success .TP \fB\fIBRLAPI_ERROR_SUCCESS \fP\fP Success .TP \fB\fIBRLAPI_ERROR_NOMEM \fP\fP Not enough memory .TP \fB\fIBRLAPI_ERROR_NOMEM \fP\fP Not enough memory .TP \fB\fIBRLAPI_ERROR_TTYBUSY \fP\fP A connection is already running in this tty .TP \fB\fIBRLAPI_ERROR_TTYBUSY \fP\fP A connection is already running in this tty .TP \fB\fIBRLAPI_ERROR_DEVICEBUSY \fP\fP A connection is already using RAW or suspend mode .TP \fB\fIBRLAPI_ERROR_DEVICEBUSY \fP\fP A connection is already using RAW or suspend mode .TP \fB\fIBRLAPI_ERROR_UNKNOWN_INSTRUCTION \fP\fP Not implemented in protocol .TP \fB\fIBRLAPI_ERROR_UNKNOWN_INSTRUCTION \fP\fP Not implemented in protocol .TP \fB\fIBRLAPI_ERROR_ILLEGAL_INSTRUCTION \fP\fP Forbiden in current mode .TP \fB\fIBRLAPI_ERROR_ILLEGAL_INSTRUCTION \fP\fP Forbiden in current mode .TP \fB\fIBRLAPI_ERROR_INVALID_PARAMETER \fP\fP Out of range or have no sense .TP \fB\fIBRLAPI_ERROR_INVALID_PARAMETER \fP\fP Out of range or have no sense .TP \fB\fIBRLAPI_ERROR_INVALID_PACKET \fP\fP Invalid size .TP \fB\fIBRLAPI_ERROR_INVALID_PACKET \fP\fP Invalid size .TP \fB\fIBRLAPI_ERROR_CONNREFUSED \fP\fP Connection refused .TP \fB\fIBRLAPI_ERROR_CONNREFUSED \fP\fP Connection refused .TP \fB\fIBRLAPI_ERROR_OPNOTSUPP \fP\fP Operation not supported .TP \fB\fIBRLAPI_ERROR_OPNOTSUPP \fP\fP Operation not supported .TP \fB\fIBRLAPI_ERROR_GAIERR \fP\fP Getaddrinfo error .TP \fB\fIBRLAPI_ERROR_GAIERR \fP\fP Getaddrinfo error .TP \fB\fIBRLAPI_ERROR_LIBCERR \fP\fP Libc error .TP \fB\fIBRLAPI_ERROR_LIBCERR \fP\fP Libc error .TP \fB\fIBRLAPI_ERROR_UNKNOWNTTY \fP\fP Couldn't find out the tty number .TP \fB\fIBRLAPI_ERROR_UNKNOWNTTY \fP\fP Couldn't find out the tty number .TP \fB\fIBRLAPI_ERROR_PROTOCOL_VERSION \fP\fP Bad protocol version .TP \fB\fIBRLAPI_ERROR_PROTOCOL_VERSION \fP\fP Bad protocol version .TP \fB\fIBRLAPI_ERROR_EOF \fP\fP Unexpected end of file .TP \fB\fIBRLAPI_ERROR_EOF \fP\fP Unexpected end of file .TP \fB\fIBRLAPI_ERROR_EMPTYKEY \fP\fP Key file empty .TP \fB\fIBRLAPI_ERROR_EMPTYKEY \fP\fP Key file empty .TP \fB\fIBRLAPI_ERROR_DRIVERERROR \fP\fP Packet returned by driver too large .TP \fB\fIBRLAPI_ERROR_DRIVERERROR \fP\fP Packet returned by driver too large .TP \fB\fIBRLAPI_ERROR_AUTHENTICATION \fP\fP Authentication failed .TP \fB\fIBRLAPI_ERROR_AUTHENTICATION \fP\fP Authentication failed .TP \fB\fIBRLAPI_ERROR_READONLY_PARAMETER \fP\fP Parameter can not be changed .TP \fB\fIBRLAPI_ERROR_READONLY_PARAMETER \fP\fP Parameter can not be changed .SH "Function Documentation" .PP .SS "void \fBBRLAPI_STDCALL\fP brlapi__defaultExceptionHandler (\fBbrlapi_handle_t\fP * handle, int error, \fBbrlapi_packetType_t\fP type, const void * packet, size_t size)" .SS "\fBbrlapi__exceptionHandler_t\fP \fBBRLAPI_STDCALL\fP brlapi__setExceptionHandler (\fBbrlapi_handle_t\fP * handle, \fBbrlapi__exceptionHandler_t\fP handler)" .SS "int \fBBRLAPI_STDCALL\fP 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)" .SS "void \fBBRLAPI_STDCALL\fP brlapi_defaultExceptionHandler (int error, \fBbrlapi_packetType_t\fP type, const void * packet, size_t size)" .SS "\fBbrlapi_error_t\fP *\fBBRLAPI_STDCALL\fP brlapi_error_location (void)" Get per-thread error location .PP 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\&. .PP This gets the thread specific location of global variable \fBbrlapi_error\fP .SS "const char *\fBBRLAPI_STDCALL\fP brlapi_getPacketTypeName (\fBbrlapi_packetType_t\fP type)" Get plain packet type .PP \fBbrlapi_getPacketTypeName()\fP returns the plain packet type name corresponding to its argument\&. .SS "void \fBBRLAPI_STDCALL\fP brlapi_perror (const char * s)" Print a BrlAPI error message .PP \fBbrlapi_perror()\fP reads \fBbrlapi_error\fP, and acts just like perror()\&. .SS "\fBbrlapi_exceptionHandler_t\fP \fBBRLAPI_STDCALL\fP brlapi_setExceptionHandler (\fBbrlapi_exceptionHandler_t\fP handler)" Set a new exception handler .PP \fBbrlapi_setExceptionHandler()\fP replaces the previous exception handler with the handler parameter\&. The previous exception handler is returned to make chaining error handlers possible\&. .PP The default handler just prints the exception and abort()s\&. .SS "const char *\fBBRLAPI_STDCALL\fP brlapi_strerror (const \fBbrlapi_error_t\fP * error)" Get plain error message .PP \fBbrlapi_strerror()\fP 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, \fBbrlapi_strerror_r()\fP should be used instead in that case\&. .SS "size_t \fBBRLAPI_STDCALL\fP brlapi_strerror_r (const \fBbrlapi_error_t\fP * error, char * buf, size_t buflen)" Store plain error message .PP \fBbrlapi_strerror_r()\fP stores the plain error message corresponding to its \fCerror\fP argument\&. \fCbuflen\fP has to be set to the size of \fCbuf\fP, and \fBbrlapi_strerror_r()\fP will store at most \fCbuflen\fP bytes in \fCbuf\fP\&. If \fCbuflen\fP 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]\&. .PP \fBReturns\fP .RS 4 the number of characters that should have been stored in \fCbuf\fP (without the trailing \\0 character)\&. A value greater or equal to \fCbuflen\fP thus means that the output was truncated\&. .RE .PP If \fCbuflen\fP is set to 0, \fCbuf\fP 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)\&. .SS "int \fBBRLAPI_STDCALL\fP brlapi_strexception (char * buffer, size_t bufferSize, int error, \fBbrlapi_packetType_t\fP type, const void * packet, size_t packetSize)" Describes an exception .PP \fBbrlapi_strexception()\fP puts a text describing the given exception in buffer\&. .PP The beginning of the guilty packet is dumped as a sequence of hex bytes\&. .PP \fBReturns\fP .RS 4 the size of the text describing the exception, following snprintf()'s semantics\&. .RE .PP .SH "Variable Documentation" .PP .SS "const char* brlapi_errfun\fC [extern]\fP" Shorthand for brlapi_error\&.errfun .SS "const char* brlapi_errlist[]\fC [extern]\fP" Error message list .PP These are the string constants used by \fBbrlapi_perror()\fP\&. .SS "enum \fBbrlapi_error\fP brlapi_errno\fC [extern]\fP" Shorthand for brlapi_error\&.errno .SS "\fBbrlapi_error_t\fP \fBbrlapi_error\fP\fC [extern]\fP" Global variable brlapi_error .PP \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\&. .PP This information may be copied in \fBbrlapi_error_t\fP variables for later use with the brlapi_strerror function\&. .SS "int brlapi_gaierrno\fC [extern]\fP" Shorthand for brlapi_error\&.gaierrno .SS "int brlapi_libcerrno\fC [extern]\fP" Shorthand for brlapi_error\&.libcerrno .SS "const int brlapi_nerr\fC [extern]\fP" Number of error messages .SH "Author" .PP Generated automatically by Doxygen for BrlAPI from the source code\&.