---
name: "brlapi_errno"
section: "3"
platform: "linux"
package: "libbrlapi-dev"
version: "6.7-3.1+deb13u3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/brlapi_error"
---

# brlapi\_errno(3)

Error handling - How to handle errors.

Part of [brlapi\_error(3)](/brlapi_error/3.md).

## NAME

brlapi\_error - Error handling

 \- How to handle errors.

## SYNOPSIS

### Data Structures

struct **brlapi\_error\_t**\

### Macros

\#define **brlapi\_error**   (\***brlapi\_error\_location**())\
 \#define **brlapi\_errno**   (brlapi\_error.brlerrno)\
 \#define **brlapi\_libcerrno**   (brlapi\_error.libcerrno)\
 \#define **brlapi\_gaierrno**   (brlapi\_error.gaierrno)\
 \#define **brlapi\_errfun**   (brlapi\_error.errfun)\

### Typedefs

typedef uint32\_t **brlapi\_packetType\_t**\
 typedef void(**BRLAPI\_STDCALL** \* **brlapi\_exceptionHandler\_t**) (int error, **brlapi\_packetType\_t** type, const void \*packet, size\_t size)\
 typedef void(**BRLAPI\_STDCALL** \* **brlapi\_\_exceptionHandler\_t**) (**brlapi\_handle\_t** \*handle, int error, **brlapi\_packetType\_t** type, const void \*packet, size\_t size)\

### Enumerations

enum **brlapi\_error** { **BRLAPI\_ERROR\_SUCCESS** = 0, **BRLAPI\_ERROR\_SUCCESS** = 0, **BRLAPI\_ERROR\_NOMEM** = 1, **BRLAPI\_ERROR\_NOMEM** = 1, **BRLAPI\_ERROR\_TTYBUSY** = 2, **BRLAPI\_ERROR\_TTYBUSY** = 2, **BRLAPI\_ERROR\_DEVICEBUSY** = 3, **BRLAPI\_ERROR\_DEVICEBUSY** = 3, **BRLAPI\_ERROR\_UNKNOWN\_INSTRUCTION** = 4, **BRLAPI\_ERROR\_UNKNOWN\_INSTRUCTION** = 4, **BRLAPI\_ERROR\_ILLEGAL\_INSTRUCTION** = 5, **BRLAPI\_ERROR\_ILLEGAL\_INSTRUCTION** = 5, **BRLAPI\_ERROR\_INVALID\_PARAMETER** = 6, **BRLAPI\_ERROR\_INVALID\_PARAMETER** = 6, **BRLAPI\_ERROR\_INVALID\_PACKET** = 7, **BRLAPI\_ERROR\_INVALID\_PACKET** = 7, **BRLAPI\_ERROR\_CONNREFUSED** = 8, **BRLAPI\_ERROR\_CONNREFUSED** = 8, **BRLAPI\_ERROR\_OPNOTSUPP** = 9, **BRLAPI\_ERROR\_OPNOTSUPP** = 9, **BRLAPI\_ERROR\_GAIERR** = 10, **BRLAPI\_ERROR\_GAIERR** = 10, **BRLAPI\_ERROR\_LIBCERR** = 11, **BRLAPI\_ERROR\_LIBCERR** = 11, **BRLAPI\_ERROR\_UNKNOWNTTY** = 12, **BRLAPI\_ERROR\_UNKNOWNTTY** = 12, **BRLAPI\_ERROR\_PROTOCOL\_VERSION** = 13, **BRLAPI\_ERROR\_PROTOCOL\_VERSION** = 13, **BRLAPI\_ERROR\_EOF** = 14, **BRLAPI\_ERROR\_EOF** = 14, **BRLAPI\_ERROR\_EMPTYKEY** = 15, **BRLAPI\_ERROR\_EMPTYKEY** = 15, **BRLAPI\_ERROR\_DRIVERERROR** = 16, **BRLAPI\_ERROR\_DRIVERERROR** = 16, **BRLAPI\_ERROR\_AUTHENTICATION** = 17, **BRLAPI\_ERROR\_AUTHENTICATION** = 17, **BRLAPI\_ERROR\_READONLY\_PARAMETER** = 18, **BRLAPI\_ERROR\_READONLY\_PARAMETER** = 18 }\

### Functions

void **BRLAPI\_STDCALL** **brlapi\_perror** (const char \*s)\
 **brlapi\_error\_t** \***BRLAPI\_STDCALL** **brlapi\_error\_location** (void)\
 const char \***BRLAPI\_STDCALL** **brlapi\_strerror** (const **brlapi\_error\_t** \*error)\
 size\_t **BRLAPI\_STDCALL** **brlapi\_strerror\_r** (const **brlapi\_error\_t** \*error, char \*buf, size\_t buflen)\
 const char \***BRLAPI\_STDCALL** **brlapi\_getPacketTypeName** (**brlapi\_packetType\_t** type)\
 int **BRLAPI\_STDCALL** **brlapi\_strexception** (char \*buffer, size\_t bufferSize, int error, **brlapi\_packetType\_t** type, const void \*packet, size\_t packetSize)\
 int **BRLAPI\_STDCALL** **brlapi\_\_strexception** (**brlapi\_handle\_t** \*handle, char \*buffer, size\_t bufferSize, int error, **brlapi\_packetType\_t** type, const void \*packet, size\_t packetSize)\
 **brlapi\_exceptionHandler\_t** **BRLAPI\_STDCALL** **brlapi\_setExceptionHandler** (**brlapi\_exceptionHandler\_t** handler)\
 **brlapi\_\_exceptionHandler\_t** **BRLAPI\_STDCALL** **brlapi\_\_setExceptionHandler** (**brlapi\_handle\_t** \*handle, **brlapi\_\_exceptionHandler\_t** handler)\
 void **BRLAPI\_STDCALL** **brlapi\_defaultExceptionHandler** (int error, **brlapi\_packetType\_t** type, const void \*packet, size\_t size)\
 void **BRLAPI\_STDCALL** **brlapi\_\_defaultExceptionHandler** (**brlapi\_handle\_t** \*handle, int error, **brlapi\_packetType\_t** type, const void \*packet, size\_t size)\

### Variables

const char \* **brlapi\_errlist** \[\]\
 const int **brlapi\_nerr**\
 **brlapi\_error\_t** **brlapi\_error**\
 enum **brlapi\_error** **brlapi\_errno**\
 int **brlapi\_libcerrno**\
 int **brlapi\_gaierrno**\
 const char \* **brlapi\_errfun**\

## Detailed Description

When a function fails, **brlapi\_errno** will hold an error code to explain why it failed. It should always be reported somehow.

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 *exception* handler. If the exception handler returns, the brlapi\_something function will return an end-of-file error.

The default exception handler (**brlapi\_defaultExceptionHandler()**) dumps the guilty packet before abort()ing. It can be replaced by calling **brlapi\_setExceptionHandler()**. For instance, the Java and Python bindings use this for raising a Java or Python exception that may be caught.

## Macro Definition Documentation

### #define brlapi\_errfun (brlapi\_error.errfun)

Cheat about the brlapi\_errfun C token

### #define brlapi\_errno (brlapi\_error.brlerrno)

Cheat about the brlapi\_errno C token

### #define brlapi\_error (\*brlapi\_error\_location())

Cheat about the brlapi\_error C token

### #define brlapi\_gaierrno (brlapi\_error.gaierrno)

Cheat about the brlapi\_gaierrno C token

### #define brlapi\_libcerrno (brlapi\_error.libcerrno)

Cheat about the brlapi\_libcerrno C token

## Typedef Documentation

### typedef void(BRLAPI\_STDCALL \* brlapi\_\_exceptionHandler\_t) (brlapi\_handle\_t \*handle, int error, brlapi\_packetType\_t type, const void \*packet, size\_t size)

### typedef void(BRLAPI\_STDCALL \* brlapi\_exceptionHandler\_t) (int error, brlapi\_packetType\_t type, const void \*packet, size\_t size)

Types for exception handlers

Types of exception handlers which are to be given to **brlapi\_setExceptionHandler()** and **brlapi\_\_setExceptionHandler()**.

**Parameters**

*error* is a BRLAPI\_ERROR\_ error code; \
 *type* is the type of the guilty packet; \
 *packet* points to the content of the guilty packet (might be a little bit truncated); \
 *size* gives the guilty packet's size.

### typedef uint32\_t brlapi\_packetType\_t

Type for packet type. Only unsigned can cross networks, 32bits

## Enumeration Type Documentation

### enum brlapi\_error

BrlAPI Error codes

**Enumerator**

- *BRLAPI\_ERROR\_SUCCESS*

  *Success*

- *BRLAPI\_ERROR\_SUCCESS*

  *Success*

- *BRLAPI\_ERROR\_NOMEM*

  *Not enough memory*

- *BRLAPI\_ERROR\_NOMEM*

  *Not enough memory*

- *BRLAPI\_ERROR\_TTYBUSY*

  *A connection is already running in this tty*

- *BRLAPI\_ERROR\_TTYBUSY*

  *A connection is already running in this tty*

- *BRLAPI\_ERROR\_DEVICEBUSY*

  *A connection is already using RAW or suspend mode*

- *BRLAPI\_ERROR\_DEVICEBUSY*

  *A connection is already using RAW or suspend mode*

- *BRLAPI\_ERROR\_UNKNOWN\_INSTRUCTION*

  *Not implemented in protocol*

- *BRLAPI\_ERROR\_UNKNOWN\_INSTRUCTION*

  *Not implemented in protocol*

- *BRLAPI\_ERROR\_ILLEGAL\_INSTRUCTION*

  *Forbiden in current mode*

- *BRLAPI\_ERROR\_ILLEGAL\_INSTRUCTION*

  *Forbiden in current mode*

- *BRLAPI\_ERROR\_INVALID\_PARAMETER*

  *Out of range or have no sense*

- *BRLAPI\_ERROR\_INVALID\_PARAMETER*

  *Out of range or have no sense*

- *BRLAPI\_ERROR\_INVALID\_PACKET*

  *Invalid size*

- *BRLAPI\_ERROR\_INVALID\_PACKET*

  *Invalid size*

- *BRLAPI\_ERROR\_CONNREFUSED*

  *Connection refused*

- *BRLAPI\_ERROR\_CONNREFUSED*

  *Connection refused*

- *BRLAPI\_ERROR\_OPNOTSUPP*

  *Operation not supported*

- *BRLAPI\_ERROR\_OPNOTSUPP*

  *Operation not supported*

- *BRLAPI\_ERROR\_GAIERR*

  *Getaddrinfo error*

- *BRLAPI\_ERROR\_GAIERR*

  *Getaddrinfo error*

- *BRLAPI\_ERROR\_LIBCERR*

  *Libc error*

- *BRLAPI\_ERROR\_LIBCERR*

  *Libc error*

- *BRLAPI\_ERROR\_UNKNOWNTTY*

  *Couldn't find out the tty number*

- *BRLAPI\_ERROR\_UNKNOWNTTY*

  *Couldn't find out the tty number*

- *BRLAPI\_ERROR\_PROTOCOL\_VERSION*

  *Bad protocol version*

- *BRLAPI\_ERROR\_PROTOCOL\_VERSION*

  *Bad protocol version*

- *BRLAPI\_ERROR\_EOF*

  *Unexpected end of file*

- *BRLAPI\_ERROR\_EOF*

  *Unexpected end of file*

- *BRLAPI\_ERROR\_EMPTYKEY*

  *Key file empty*

- *BRLAPI\_ERROR\_EMPTYKEY*

  *Key file empty*

- *BRLAPI\_ERROR\_DRIVERERROR*

  *Packet returned by driver too large*

- *BRLAPI\_ERROR\_DRIVERERROR*

  *Packet returned by driver too large*

- *BRLAPI\_ERROR\_AUTHENTICATION*

  *Authentication failed*

- *BRLAPI\_ERROR\_AUTHENTICATION*

  *Authentication failed*

- *BRLAPI\_ERROR\_READONLY\_PARAMETER*

  *Parameter can not be changed*

- *BRLAPI\_ERROR\_READONLY\_PARAMETER*

  *Parameter can not be changed*

## Function Documentation

### void BRLAPI\_STDCALL brlapi\_\_defaultExceptionHandler (brlapi\_handle\_t \* handle, int error, brlapi\_packetType\_t type, const void \* packet, size\_t size)

### brlapi\_\_exceptionHandler\_t BRLAPI\_STDCALL brlapi\_\_setExceptionHandler (brlapi\_handle\_t \* handle, brlapi\_\_exceptionHandler\_t handler)

### int BRLAPI\_STDCALL brlapi\_\_strexception (brlapi\_handle\_t \* handle, char \* buffer, size\_t bufferSize, int error, brlapi\_packetType\_t type, const void \* packet, size\_t packetSize)

### void BRLAPI\_STDCALL brlapi\_defaultExceptionHandler (int error, brlapi\_packetType\_t type, const void \* packet, size\_t size)

### brlapi\_error\_t \*BRLAPI\_STDCALL brlapi\_error\_location (void)

*Get per-thread error location*

*In multithreaded software,* **brlapi\_error** *is thread-specific, so api.h cheats about the brlapi\_error token and actually calls* **brlapi\_error\_location()***.*

*This gets the thread specific location of global variable* **brlapi\_error**

### const char \*BRLAPI\_STDCALL brlapi\_getPacketTypeName (brlapi\_packetType\_t type)

*Get plain packet type*

**brlapi\_getPacketTypeName()** *returns the plain packet type name corresponding to its argument.*

### void BRLAPI\_STDCALL brlapi\_perror (const char \* s)

*Print a BrlAPI error message*

**brlapi\_perror()** *reads* **brlapi\_error***, and acts just like perror().*

### brlapi\_exceptionHandler\_t BRLAPI\_STDCALL brlapi\_setExceptionHandler (brlapi\_exceptionHandler\_t handler)

*Set a new exception handler*

**brlapi\_setExceptionHandler()** *replaces the previous exception handler with the handler parameter. The previous exception handler is returned to make chaining error handlers possible.*

*The default handler just prints the exception and abort()s.*

### const char \*BRLAPI\_STDCALL brlapi\_strerror (const brlapi\_error\_t \* error)

*Get plain error message*

**brlapi\_strerror()** *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,* **brlapi\_strerror\_r()** *should be used instead in that case.*

### size\_t BRLAPI\_STDCALL brlapi\_strerror\_r (const brlapi\_error\_t \* error, char \* buf, size\_t buflen)

*Store plain error message*

**brlapi\_strerror\_r()** *stores the plain error message corresponding to its* `error` *argument.* `buflen` *has to be set to the size of* `buf`*, and* **brlapi\_strerror\_r()** *will store at most* `buflen` *bytes in* `buf`*. If* `buflen` *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\].*

**Returns**

*the number of characters that should have been stored in* `buf` *(without the trailing \\0 character). A value greater or equal to* `buflen` *thus means that the output was truncated.*

*If* `buflen` *is set to 0,* `buf` *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).*

### int BRLAPI\_STDCALL brlapi\_strexception (char \* buffer, size\_t bufferSize, int error, brlapi\_packetType\_t type, const void \* packet, size\_t packetSize)

*Describes an exception*

**brlapi\_strexception()** *puts a text describing the given exception in buffer.*

*The beginning of the guilty packet is dumped as a sequence of hex bytes.*

**Returns**

*the size of the text describing the exception, following snprintf()'s semantics.*

## Variable Documentation

### const char\* brlapi\_errfun` [extern]`

*Shorthand for brlapi\_error.errfun*

### const char\* brlapi\_errlist\[\]` [extern]`

*Error message list*

*These are the string constants used by* **brlapi\_perror()***.*

### enum brlapi\_error brlapi\_errno` [extern]`

*Shorthand for brlapi\_error.errno*

### brlapi\_error\_t brlapi\_error` [extern]`

*Global variable brlapi\_error*

**brlapi\_error** *is a global left-value containing the last error information. Its errno field is not reset to BRLAPI\_ERROR\_SUCCESS on success.*

*This information may be copied in* **brlapi\_error\_t** *variables for later use with the brlapi\_strerror function.*

### int brlapi\_gaierrno` [extern]`

*Shorthand for brlapi\_error.gaierrno*

### int brlapi\_libcerrno` [extern]`

*Shorthand for brlapi\_error.libcerrno*

### const int brlapi\_nerr` [extern]`

*Number of error messages*

## Author

*Generated automatically by Doxygen for BrlAPI from the source code.*