ERR_NEW(3ossl)

💖 ERR_NEW(3ossl) — the OpenSSL error-recording building blocks 💖

okay bestie, this is the ossl manual, and we're talking about the little glue pieces that make error reporting happen. It's giving "backstage crew" energy — you don't usually see them, but the whole show falls apart without them. 🎀

---

✨ NAME ✨

ERR_new, ERR_set_debug, ERR_set_error, ERR_vset_error — error recording building blocks 🧱💅

---

🌸 SYNOPSIS 🌸

#include <openssl/err.h>

void ERR_new(void);
void ERR_set_debug(const char *file, int line, const char *func);
void ERR_set_error(int lib, int reason, const char *fmt, ...);
void ERR_vset_error(int lib, int reason, const char *fmt, va_list args);

---

🦋 DESCRIPTION 🦋

So like… these functions? Not the ones you'd normally call directly, no cap. Most of the time you reach them through macros like ERR_raise(3) and never think about it again. BUT — and this is the iconic part — if you wanna build your own macros, these are exactly the little lego bricks you'd use. ✨

• ERR_new() — allocates a brand new slot in the thread's error queue. Fresh slot, fresh start, main character moment. 💫
• ERR_set_debug() — sets the debug info for the current error sitting in the thread's error queue. The values you can hand it are: the filename file, the line in the file line, and the name of the function func where the error went down. ⚠️ Important: those names must be constant — this function only saves away the pointers, it does not copy the strings. So don't be out here passing a stack buffer that's about to dip, fr fr.
• ERR_set_error() — sets the actual error information: the library number lib, the reason code reason, plus extra data as a format string fmt and however many arguments you feel like throwing at it. That extra data gets processed with BIO_snprintf(3) to build the additional data string, and that string is allocated and stored in the error record. 🍓
• ERR_vset_error() — literally the same as ERR_set_error() but it takes a va_list argument instead of a variable number of arguments. Same vibe, different signature. 💜

---

🌈 RETURN VALUES 🌈

ERR_new, ERR_set_debug, ERR_set_error and ERR_vset_error do not return any values. Nothing. Nada. They're void and they're at peace with it. 😌

---

👑 NOTES 👑

The library number is unique to each unit that records errors. OpenSSL has a bunch of preallocated ones for its own uses, but other people can allocate their own library number dynamically with ERR_get_next_error_library(3). So you can get your own, you're not stuck borrowing someone else's. 🫶

Reason codes are unique within each library, and they may have an associated set of strings acting as a short description of the reason. For dynamically allocated library numbers, those reason strings get recorded with ERR_load_strings(3). 📝

Provider authors, this one's for you: you get supplied with core versions of these functions — check provider-base(7). 💅

---

🔥 SEE ALSO 🔥

ERR_raise(3), ERR_get_next_error_library(3), ERR_load_strings(3), BIO_snprintf(3), provider-base(7)

---

💜 COPYRIGHT 💜

Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

---

okay that's the whole thing, no skips, no summaries, we kept every single detail because that's just how we do it around here 💖

and that's a wrap bestie — this was ERR_NEW(3ossl) from OpenSSL 3.5.9, dated 2026-09-29. slay, go forth and raise errors responsibly ✨🎀💅