RAWAPI//docs

$ man rawapi

Low-level systems programming interface. No abstractions. No magic.

// rawapi_example.c

#include <rawapi/core.h>

#include <rawapi/mem.h>

int main(void) {

raw_ctx_t *ctx = raw_init(RAW_DEFAULT);

raw_buf_t *buf = raw_alloc(ctx, 4096);

raw_write(buf, data, len);

raw_flush(ctx);

raw_destroy(ctx);

return 0;

}

// Core Concepts

Contexts

Every RAWAPI operation requires a context. Contexts manage memory arenas, file descriptors, and signal handlers. A context is thread-local by default; use raw_ctx_share() for cross-thread access with explicit locking.

Buffers

Buffers are fixed-size memory regions allocated from the context arena. They support zero-copy reads, scatter-gather I/O, and automatic alignment to cache-line boundaries. Buffers cannot be resized after allocation.

Pipelines

Chain multiple operations into a pipeline for batch execution. The runtime fuses compatible operations and eliminates intermediate copies. Pipelines are submitted atomically to the kernel via io_uring.

Arenas

Memory arenas provide bump-pointer allocation with O(1) free. Each context owns one arena by default. Arena size is configurable at init time via RAW_ARENA_SIZE. When an arena is exhausted, raw_alloc returns NULL rather than falling back to malloc.

Descriptors

File descriptors are managed through the context. Use raw_open() and raw_close() instead of system calls directly. The context tracks descriptor lifetime and ensures cleanup on raw_destroy(), preventing resource leaks.

// Function Reference

FunctionSignatureDescription
raw_init(uint32_t flags) -> raw_ctx_t*Initialize a new context with the given configuration flags
raw_alloc(raw_ctx_t*, size_t) -> raw_buf_t*Allocate a buffer from the context memory arena
raw_write(raw_buf_t*, void*, size_t) -> ssize_tWrite data into buffer, returns bytes written or -1
raw_read(raw_buf_t*, void*, size_t) -> ssize_tRead data from buffer into destination, returns bytes read
raw_flush(raw_ctx_t*) -> intFlush all pending operations to their destinations
raw_pipe(raw_ctx_t*, raw_op_t*, int) -> intSubmit a pipeline of operations for batch execution
raw_open(raw_ctx_t*, char*, int) -> intOpen a file descriptor managed by the context
raw_close(raw_ctx_t*, int) -> intClose a managed file descriptor and release resources
raw_mmap(raw_ctx_t*, size_t, int) -> void*Memory-map a region tracked by the context arena
raw_destroy(raw_ctx_t*) -> voidTear down context and release all associated resources

// Error Codes

RAW_OK (0)Operation completed successfully
RAW_ENOMEM (-1)Arena out of memory, context cannot allocate
RAW_EIO (-2)I/O error on underlying file descriptor
RAW_EINVAL (-3)Invalid argument passed to function
RAW_EBUSY (-4)Resource is locked by another thread
RAW_EPIPE (-5)Pipeline submission failed, partial execution
RAW_ENOSYS (-6)Operation not supported on this platform
RAW_ETIMEOUT (-7)Operation exceeded the configured deadline
RAW_EOVERFLOW (-8)Buffer write would exceed allocated capacity

// Platform Support

Linux

x86_64, aarch64

Kernel 5.10+ (io_uring)

glibc 2.31+, musl

macOS

x86_64, arm64

macOS 13+ (kqueue fallback)

Xcode 14+ toolchain

FreeBSD

x86_64, aarch64

FreeBSD 13+ (kqueue)

Clang 15+ or GCC 12+

// Community

IRC

#rawapi on Libera.Chat. Core maintainers are active daily. Logs available at logs.rawapi.dev.

Mailing List

rawapi-dev@lists.rawapi.dev for patches and RFCs. rawapi-users@ for usage questions and discussion.

Source

git.rawapi.dev/rawapi/core. Mirror on GitHub. Contributions require signed-off-by and passing CI.

$ git clone git://git.rawapi.dev/rawapi/core.git

$ cd core && make && make test

$ sudo make install PREFIX=/usr/local

rawapi@docs:~$RAWAPI v0.9.3 | ISC License | Built with zero dependencies