Unwrapping a C pointer with .? is an assertion

Nullness isn't the only thing that pointer drops. The length goes too. Once the wrapper has turned the result into a [*]u8, it's the last place that knows n. I'd return p[0..n] as a slice, so the caller gets the address and the length together and bounds checks have something to work with.

The return type also can't say who frees it, so the doc comment has to. Memory from c.malloc goes back through c.free, not through whatever allocator the caller usually passes around. If the wrapper doesn't need malloc specifically, allocating through std.heap.c_allocator keeps that pairing inside Zig's own allocator interface.

On which error to name, the information is usually in errno, and the one rule that never changes is to read it right after the call, before anything else can run. Logging, a formatting call, really any library function is allowed to change it even when nothing failed. Python's ctypes has the same trap, which is why it makes you ask for use_errno=True and then read ctypes.get_errno() instead of the raw variable.

So the step order I'd write down is call, check for null, copy errno into a local, then decide which error it maps to. The mapping can be a switch over a few known values with a catch-all for the rest, and that last branch is where most of the judgment goes.

Agreed on the slice. The wrapper returns []u8 now, and its doc comment names c.free as the release, with a sentence for the error path too, where nothing is returned and nothing needs freeing.

I'm keeping malloc itself, because the buffer is handed to a C function that may call realloc on it later. That is a transfer to C, and once it happens the slice I returned stops being valid as well, which the doc comment now says.

Look at what that catch-all branch can return, though. A Zig error is just a name. It carries no payload, so else => error.Unexpected drops the errno value that told you what actually happened. If the value matters later, it has to travel some other way, an out parameter or a diagnostics struct the caller passes in, and the error name only says which kind of thing went wrong.

I'd keep the known branches as small as possible, one errno to one name each, so a reader can check each case against the C man page without reading the others.

Close to TypeScript's !, which compiles to nothing, except that Zig's .? panics in a safety-checked build. Under ReleaseFast that check is gone, so the one you leaned on in testing isn't in the build you ship.