boredos_mirror/docs/appdev/libc_reference.md

# libc Reference

This page documents the current BoredOS userland libc surface from `src/userland/libc/`.

BoredOS libc is a compact implementation focused on the APIs used by in-tree apps. It is not a full glibc replacement.

## Header Overview

| Header | Focus |
|---|---|
| `stdlib.h` | allocation, conversion, process helpers |
| `string.h` | memory/string primitives |
| `stdio.h` | `FILE*` and formatted I/O |
| `unistd.h` | POSIX-like fd/process calls |
| `fcntl.h` | open/fcntl flags, `dup`, `pipe` |
| `input.h` | keyboard keycode constants |
| `signal.h` | signal handlers and masks |
| `sys/stat.h` | `stat`/`fstat` and file mode bits |
| `sys/types.h` | core typedefs (`pid_t`, `ssize_t`, ...) |
| `sys/wait.h` | `waitpid` and wait macros |
| `errno.h` | errno values |
| `time.h` | time/date utilities |
| `math.h` | floating-point math helpers |
| `libui.h` | GUI/window drawing API |

## stdlib.h

Implemented core functions:
- Memory: `malloc`, `free`, `calloc`, `realloc`
- Memory aliases: `memset`, `memcpy`
- Conversions: `atoi`, `itoa`, `strtod`, `abs`
- Output: `puts`, `printf`
- Process/environment: `exit`, `_exit`, `sleep`, `chdir`, `getcwd`, `access`, `system`, `getenv`, `abort`

Notes:
- `sleep` is millisecond-based and maps to kernel sleep command.
- `system` is a stub-style helper in this libc, not a full shell launcher equivalent.

## string.h

Implemented C string/memory set includes:
- Memory: `memmove`, `memcmp`, `memcpy`, `memset`, `memchr`
- Search: `strchr`, `strrchr`, `strpbrk`, `strstr`
- Span: `strspn`, `strcspn`
- Compare: `strcmp`, `strncmp`, `strcasecmp`, `strncasecmp`, `strcoll`
- Build/copy: `strlen`, `strcpy`, `strcat`, `strdup`
- Errors: `strerror`

## stdio.h

Provided API includes:
- Stream open/close: `fopen`, `freopen`, `fclose`
- Read/write: `fread`, `fwrite`, `fgets`, `fputs`, `getc`, `fputc`, `putchar`
- Positioning: `fseek`, `ftell`, `filelength`
- Formatting: `fprintf`, `vfprintf`, `snprintf`, `vsnprintf`, `sprintf`, `sscanf`
- Stream state: `feof`, `ferror`, `clearerr`, `fflush`, `ungetc`
- Temp/filesystem helpers: `remove`, `rename`, `tmpfile`, `tmpnam`

## unistd.h

Provided POSIX-like interfaces:
- FD I/O: `read`, `write`, `close`, `lseek`, `isatty`
- Filesystem: `unlink`
- Exec family: `execv`, `execve`, `execvp`, `execl`, `execlp`, `execle`
- Process wait: `waitpid`

Also defines:
- `SEEK_SET`, `SEEK_CUR`, `SEEK_END`
- `F_OK`, `X_OK`, `W_OK`, `R_OK`

## fcntl.h

Flags and fd control:
- Open flags: `O_RDONLY`, `O_WRONLY`, `O_RDWR`, `O_CREAT`, `O_EXCL`, `O_TRUNC`, `O_APPEND`, `O_NONBLOCK`, `O_ACCMODE`
- fcntl ops: `F_GETFL`, `F_SETFL`
- FD flag: `FD_CLOEXEC` (declared)

Functions:
- `open`
- `fcntl`
- `dup`
- `dup2`
- `pipe`

## input.h

Defines keyboard/control keycode constants used by apps that process

Current constants include:
- Arrow keys: `KEY_UP`, `KEY_DOWN`, `KEY_LEFT`, `KEY_RIGHT`
- Controls: `KEY_ENTER`, `KEY_BACKSPACE`, `KEY_ESCAPE`, `KEY_SPACE`, `KEY_ALT`, `KEY_CTRL_L`, `KEY_TAB`

## signal.h

Current signal surface:
- Basic handler API: `signal`, `raise`, `kill`
- POSIX-style API: `sigaction`, `sigprocmask`, `sigpending`
- Types: `sighandler_t`, `sigset_t`, `struct sigaction`
- Constants: `SIGINT`, `SIGTERM`, `SIGKILL`, `SIG_DFL`, `SIG_IGN`, `SIG_ERR`
- Mask ops: `SIG_BLOCK`, `SIG_UNBLOCK`, `SIG_SETMASK`
- Action flags: `SA_RESTART`, `SA_NODEFER`, `SA_RESETHAND`

## ctype.h

Character classification and case conversion:
- `isdigit`, `isalpha`, `isalnum`, `isspace`
- `isupper`, `islower`, `isxdigit`
- `iscntrl`, `ispunct`, `isprint`, `isgraph`
- `tolower`, `toupper`

## locale.h

Locale stubs and conventions:
- `struct lconv`
- `setlocale`
- `localeconv`
- `LC_ALL`

## limits.h

Integer and floating-point limit macros:
- `CHAR_BIT`, `INT_MIN`, `INT_MAX`, `UINT_MAX`
- `LONG_MIN`, `LONG_MAX`, `ULONG_MAX`
- `LLONG_MIN`, `LLONG_MAX`, `ULLONG_MAX`
- `DBL_MAX`

## setjmp.h

Non-local jump support:
- `jmp_buf`
- `setjmp`
- `longjmp`

## time.h

Time/date APIs and types:
- Types: `time_t`, `clock_t`, `struct tm`
- Constants: `CLOCKS_PER_SEC`
- Functions: `time`, `clock`, `localtime`, `gmtime`, `strftime`, `mktime`

## libui.h

Windowing and drawing API used by GUI apps:
- Window/event: `ui_window_create`, `ui_get_event`, `ui_mark_dirty`, `ui_window_set_title`, `ui_window_set_resizable`
- Drawing: `ui_draw_rect`, `ui_draw_rounded_rect_filled`, `ui_draw_string`, `ui_draw_string_bitmap`, `ui_draw_image`
- Text metrics/scaled text: `ui_get_string_width`, `ui_get_font_height`, `ui_draw_string_scaled`, `ui_draw_string_scaled_sloped`, `ui_get_string_width_scaled`, `ui_get_font_height_scaled`
- System UI helpers: `ui_get_screen_size`, `ui_set_font`

## sys/stat.h and sys/types.h

`sys/stat.h` provides:
- `struct stat`
- `stat`, `fstat`, `mkdir`
- mode/type macros (`S_IFREG`, `S_IFDIR`, `S_ISREG`, `S_ISDIR`, permission bits)

Note:
- `access` is declared in `stdlib.h` in this libc.

`sys/types.h` provides:
- `ssize_t`, `off_t`, `mode_t`, `pid_t`, `uid_t`, `gid_t`

## sys/wait.h

- `waitpid`
- `WNOHANG`
- status macros: `WEXITSTATUS`, `WIFEXITED`, `WTERMSIG`, `WIFSIGNALED`

## errno.h

Defined errno values include:
- Generic/input: `EINVAL`, `EDOM`, `ERANGE`, `E2BIG`
- File/path: `ENOENT`, `EEXIST`, `EISDIR`, `ENOTDIR`, `EBADF`
- Runtime/state: `ENOMEM`, `EACCES`, `EIO`, `EAGAIN`, `EINTR`, `ECHILD`, `EBUSY`, `EPIPE`, `ESPIPE`, `ENOSYS`, `ENOTSUP`

## Relationship to raw syscalls

- libc high-level I/O and process APIs are backed by wrappers in `src/userland/libc/syscall.c`.
- Full syscall command IDs and multiplexer details are documented in `docs/appdev/syscalls.md`.

## Practical Guidance

- Prefer libc APIs (`open`, `read`, `write`, `waitpid`, `sigaction`) for portability inside BoredOS userland.
- Use raw wrapper calls from `syscall.h` only for capabilities that do not yet have higher-level libc wrappers.
- Avoid numeric `sys_system(...)` command literals in app code; use `SYSTEM_CMD_*` macros.