.TH "brlapi_error" 3 "Thu Sep 07 2023" "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\&.