brlapi_error(3)

✨ NAME ✨

brlapi_error — Error handling, bestie 💖

• How to handle errors.

ok so this is the <pink>brlapi_error(3)</pink> page from the Library Functions Manual. it's a long one so we're splitting it — this is part 1, stay with me 🫶

---

🌸 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 💅

okay so here's the whole vibe: when a function fails, brlapi_errno will hold an error code that explains why it failed. and like… you should always report it somehow, bestie. don't just swallow it, that's giving "I don't debug" energy 😭

although most errors get reported that way, some of them — the ones we call exceptions — get 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 one of those happens, the next call to brlapi_something will close the connection and call the exception handler. and 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. yes, abort()ing, we're not playing. 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. iconic behavior honestly 🐍☕

---

🎀 Macro Definition Documentation 🎀

#define brlapi_errfun (brlapi_error.errfun)

Cheat about the brlapi_errfun C token.

Referenced by brlapi_error_location().

#define brlapi_errno (brlapi_error.brlerrno)

Cheat about the brlapi_errno C token.

Referenced by brlapi_error_location().

#define brlapi_error (*brlapi_error_location())

Cheat about the brlapi_error C token.

Referenced by brlapi_error_location().

#define brlapi_gaierrno (brlapi_error.gaierrno)

Cheat about the brlapi_gaierrno C token.

Referenced by brlapi_error_location().

#define brlapi_libcerrno (brlapi_error.libcerrno)

Cheat about the brlapi_libcerrno C token.

Referenced by brlapi_error_location().

---

🦋 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.

these are the types of exception handlers which are to be given to brlapi_setExceptionHandler() and brlapi__setExceptionHandler(). slay 🫶

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. no cap ✨

---

🌈 Enumeration Type Documentation 🌈

enum brlapi_error

BrlAPI Error codes 💖

Enumerator

heads up bestie: the original docs list every single one of these twice — so we're listing them twice too. we don't gatekeep, we don't skip, we keep every detail fr fr 💅

• 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 💖

Okay bestie, this is the part where we meet the actual functions. Every single one of them. Grab a snack 🍓

---

🌸 void BRLAPI_STDCALL brlapi__defaultExceptionHandler (brlapi_handle_t * handle, int error, brlapi_packetType_t type, const void * packet, size_t size)

The internal default exception handler, fr fr. It references BRLAPI_STDCALL.

---

🌸 brlapi__exceptionHandler_t BRLAPI_STDCALL brlapi__setExceptionHandler (brlapi_handle_t * handle, brlapi__exceptionHandler_t handler)

The internal exception handler setter, bestie. It references BRLAPI_STDCALL.

---

🌸 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)

The internal version of the exception stringifier 💅. It references BRLAPI_STDCALL.

---

🌸 void BRLAPI_STDCALL brlapi_defaultExceptionHandler (int error, brlapi_packetType_t type, const void * packet, size_t size)

The public default exception handler, periodt. It references BRLAPI_STDCALL.

---

🌸 brlapi_error_t *BRLAPI_STDCALL brlapi_error_location (void )

Get per-thread error location — no cap, that's literally what it does.

So here's the tea: in multithreaded software, brlapi_error is thread-specific. Which means api.h is out here cheating about the brlapi_error token and actually calls brlapi_error_location() instead. Sneaky but iconic. 🙈

This gets the thread specific location of global variable brlapi_error.

It references brlapi_errfun, brlapi_errno, brlapi_error, brlapi_gaierrno, brlapi_libcerrno, and BRLAPI_STDCALL.

---

🌸 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.

It references BRLAPI_STDCALL.

---

🌸 void BRLAPI_STDCALL brlapi_perror (const char * s)

Print a BrlAPI error message 🎀

brlapi_perror() reads brlapi_error, and acts just like perror().

It references BRLAPI_STDCALL.

---

🌸 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, which is how you make chaining error handlers possible. Cute, right?

⚠️ Heads up bestie: the default handler just prints the exception and abort()s. Like, it literally ends the whole program. So maybe don't rely on it if you're not about that life. 💀

It references BRLAPI_STDCALL.

---

🌸 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.

🚨 Two things, and they matter: 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. iykyk.

It references BRLAPI_STDCALL.

---

🌸 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]. Safety first, always. 🫶

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). Size-probing era, we love to see it. 🔥

It references BRLAPI_STDCALL.

---

🌸 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. Yes bestie, it's naming names. 💅

Returns

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

It references BRLAPI_STDCALL.

---

🦋 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 — so don't go assuming a clean slate, okay? 🙈

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.

---

And that's a wrap on brlapi_error(3), bestie!! 🎀 This whole thing came from BrlAPI, Version 0.8, and it's the brlapi_error(3) page — generated straight from the source code by Doxygen. Slay, stay safe, and always check your brlapi_error 💖✨🦋