SDL_INOUT_Z_CAP(3)

✨ SDL_INOUT_Z_CAP ✨

okay bestie, so this one lives in the SDL3 FUNCTIONS section of your manual, and it's genuinely such a tiny macro but it's doing the MOST for your code hygiene, periodt. 💅

---

🌸 NAME 🌸

SDL_INOUT_Z_CAP — a macro that annotates function params with input/output string buffer size. it's giving "little label, big consequences" energy fr fr. 🎀

---

🦋 SYNOPSIS 🦋

#include <SDL3/SDL_stdinc.h>

#define SDL_INOUT_Z_CAP(x) _Inout_z_cap_(x)

like, that's the whole thing. one line of #define and it's already iconic. 👑

---

💖 DESCRIPTION 💖

so picture this: you've got a function, and one of its params is a buffer that gets read from AND written to. how does the compiler know how big that thing is supposed to be? it doesn't! unless you tell it. and that's literally what this macro is for. 🔥

if we were to annotate strlcat, it'd look like this:

size_t strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen);

and the way this reads — this notes that dst is a null-terminated C string, should be maxlen bytes in size, and is both read from and written to by the function. all three of those facts, just from one little macro sitting there being cute. 🫶

and then the payoff: the compiler or other analysis tools can warn when this doesn't appear to be the case. so if someone calls it with a buffer that's too small or not null-terminated like it should be, you get a heads up instead of a mystery crash three hours later. it's giving protective bestie energy, ngl. 😭✨

⚠️ important caveat: on compilers without this annotation mechanism, this is defined to nothing. so it's not a runtime thing, it's not a safety net that exists everywhere — it just evaporates on toolchains that can't use it. no cap. 💀

---

🌈 AVAILABILITY 🌈

this macro is available since SDL 3.2.0. so if you're on something older, sorry babe, you don't got it. 🙈

---

💜 that's it, that's the page 💜

go annotate your buffers and let the compiler gas you up when you're right. main character energy only. ⭐🧚

Simple Directmedia Layer — SDL 3.4.18 — SDL_INOUT_Z_CAP(3) 🎀 bye bestie, slay responsibly 💖