boredos_mirror/docs/appdev/sdk_reference.md

Userland SDK Reference

Comprehensive manual for custom libc and system calls in BoredOS.

---

BoredOS provides a custom libc implementation necessary for writing userland applications (.elf binaries). By avoiding a full-blown standard library like glibc, the OS ensures a minimal executable footprint tailored strictly to the existing kernel features.

All headers are located in src/userland/libc/ (standard functions) and src/wm/ (UI and widgets).

• stdlib.h: Memory, strings, and basic I/O.
• math.h: Freestanding floating-point math library.
• libui.h: Core window and drawing API.
• libwidget.h: High-level UI components.

Standard Library (stdlib.h & string.h)

The standard library wrappers provide memory management, string manipulation, and basic IO formatting without needing direct syscalls.

Memory Allocation

• void* malloc(size_t size); - Allocate a block of memory on the heap.
• void free(void* ptr); - Free a previously allocated memory block.
• void* calloc(size_t nmemb, size_t size); - Allocate and zero-out a block of memory for an array.
• void* realloc(void* ptr, size_t size); - Resize an existing memory block.

Memory Manipulation (string.h)

• void* memset(void *s, int c, size_t n); - Fill a block of memory with a specific byte.
• void* memcpy(void *dest, const void *src, size_t n); - Copy memory from source to destination.
• void* memmove(void *dest, const void *src, size_t n); - Safely copy overlapping memory blocks.
• int memcmp(const void *s1, const void *s2, size_t n); - Compare two memory blocks.

String Utilities

• size_t strlen(const char *s); - Get the length of a string.
• int strcmp(const char *s1, const char *s2); - Compare two strings lexicographically.
• char* strcpy(char *dest, const char *src); - Copy a string to a destination buffer.
• char* strcat(char *dest, const char *src); - Concatenate two strings.

Conversion and Formatting

• int atoi(const char *nptr); - String to integer conversion.
• void itoa(int n, char *buf); - Integer to string conversion.

Input / Output

• void puts(const char *s); - Print a string followed by a newline to the standard output.
• void printf(const char *fmt, ...); - Formatted print to standard output (supports %d, %s, %x, etc.).

Process Control

• void exit(int status); - Terminate the current process.
• void sleep(int ms); - Pause execution for a specified number of milliseconds.

---

Math Library (math.h)

BoredOS ships a freestanding floating-point math library in libc/math.h. It uses pure arithmetic — Taylor series, Newton-Raphson, and range-reduction — with no dependency on a host libm or hardware math intrinsics. It is automatically linked into every userland ELF.

#include "math.h"

Constants

Constant	Value	Description
M_PI	3.14159…	π
M_E	2.71828…	Euler's number
M_LN2	0.69315…	Natural log of 2
M_SQRT2	1.41421…	√2
HUGE_VAL	~+∞	Overflow sentinel

Functions

Absolute value & remainder

• double fabs(double x); — Absolute value.
• double fmod(double x, double y); — Floating-point remainder. Returns 0 when y == 0.

Rounding

• double floor(double x); — Largest integer ≤ x.
• double ceil(double x); — Smallest integer ≥ x.

Trigonometry (arguments in radians)

• double sin(double x); — Sine. Range-reduced to [-π, π] then computed via 8-term Taylor series.
• double cos(double x); — Cosine. Computed via sin(x + π/2).
• double tan(double x); — Tangent. Returns sentinel 1e15 near poles.

Exponential & logarithm

• double sqrt(double x); — Square root via Newton-Raphson (25 iterations). Returns 0 for x ≤ 0.
• double log(double x); — Natural logarithm (ln). Returns -1e30 for x ≤ 0.
• double log2(double x); — Base-2 logarithm.
• double log10(double x); — Base-10 logarithm.
• double exp(double x); — e^x. Saturates to 1e300 for x > 700, 0 for x < -700.
• double pow(double base, double exponent); — General power. Integer exponents use fast binary exponentiation; fractional exponents use exp(e * log(b)).

Hyperbolic

• double sinh(double x); — Hyperbolic sine.
• double cosh(double x); — Hyperbolic cosine.
• double tanh(double x); — Hyperbolic tangent.

Utility

• double hypot(double x, double y); — sqrt(x² + y²) without intermediate overflow.
• double fmin(double a, double b); — Minimum of two values.
• double fmax(double a, double b); — Maximum of two values.
• double fclamp(double x, double lo, double hi); — Clamps x into [lo, hi].

Note

The implementation file is named libc/libmath.c (not libc/math.c) to avoid a name collision with the math CLI calculator app in userland. The public header is still included as #include "math.h".

For advanced operations, syscall.h provides direct wrappers into the kernel.

Process & System Info

• void sys_exit(int status); - Raw exit syscall.
• int sys_write(int fd, const char *buf, int len); - Write to a file descriptor (usually fd 1 for stdout).
• void* sys_sbrk(int incr); - Expand or shrink the process data segment (used internally by malloc).
• void sys_kill(int pid); - Send a kill signal to a process.
• void sys_yield(void); - Yield the remainder of the process's timeslice to the scheduler.
• int sys_system(int cmd, uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4); - Execute a privileged system command (e.g., reboot, shutdown, beep).
• int sys_get_os_info(os_info_t *info); - Populate an os_info_t struct with version and environment details.
• uint64_t sys_get_shell_config(const char *key); - Retrieve internal shell configuration values.
• void sys_set_text_color(uint32_t color); - Set the raw CLI text output color.

File System API (VFS)

Interacting with files and directories using the Virtual File System.

• int sys_open(const char *path, const char *mode); - Open a file, returning a file descriptor.
• int sys_read(int fd, void *buf, uint32_t len); - Read from an open file.
• int sys_write_fs(int fd, const void *buf, uint32_t len); - Write to an open file.
• void sys_close(int fd); - Close an open file descriptor.
• int sys_seek(int fd, int offset, int whence); - Reposition the file offset.
• uint32_t sys_tell(int fd); - Get the current file offset.
• uint32_t sys_size(int fd); - Get the total file size.
• int sys_delete(const char *path); - Delete a file.
• int sys_mkdir(const char *path); - Create a new directory.
• int sys_exists(const char *path); - Check if a path exists on the filesystem.
• int sys_getcwd(char *buf, int size); - Get the current working directory string.
• int sys_chdir(const char *path); - Change the current working directory.
• int sys_list(const char *path, FAT32_FileInfo *entries, int max_entries); - List directory contents into an array of FAT32_FileInfo structs.
• int sys_get_file_info(const char *path, FAT32_FileInfo *info); - Retrieve metadata for a specific file.

Networking Stack API

BoredOS includes lwIP for hardware TCP/UDP networking.

Configuration and Status

• int sys_network_init(void); - Initialize the network stack.
• int sys_network_is_initialized(void); - Check stack status.
• int sys_network_dhcp_acquire(void); - Request an IP configuration from a DHCP server.
• int sys_network_has_ip(void); - Check if the system has a valid IP address.
• int sys_network_get_mac(net_mac_address_t *mac); - Get the physical MAC address of the NIC.
• int sys_network_get_nic_name(char *name_out); - Get the name of the active network interface card.
• int sys_network_get_ip(net_ipv4_address_t *ip); - Get current local IPv4 address.
• int sys_network_set_ip(const net_ipv4_address_t *ip); - Manually assign a static IP.
• int sys_network_get_gateway(net_ipv4_address_t *ip); - Get the default gateway IP.
• int sys_network_get_dns(net_ipv4_address_t *ip); - Get the primary DNS server IP.
• int sys_set_dns_server(const net_ipv4_address_t *ip); - Set the primary DNS server.
• int sys_get_dns_server(net_ipv4_address_t *ip); - Retrieve configured DNS server.
• int sys_network_get_stat(int stat_type); - Get network statistics (packets in/out, drops, etc.).
• void sys_network_force_unlock(void); - Force release of network stack locks (use with caution).

Communication

• int sys_icmp_ping(const net_ipv4_address_t *dest_ip); - Send an ICMP echo request.
• int sys_udp_send(const net_ipv4_address_t *dest_ip, uint16_t dest_port, uint16_t src_port, const void *data, size_t data_len); - Send a raw UDP datagram.
• int sys_dns_lookup(const char *name, net_ipv4_address_t *out_ip); - Resolve a hostname to an IPv4 address.
• int sys_tcp_connect(const net_ipv4_address_t *ip, uint16_t port); - Establish a TCP connection to a remote host.
• int sys_tcp_send(const void *data, size_t len); - Send data over an active TCP socket.
• int sys_tcp_recv(void *buf, size_t max_len); - Receive data from a TCP socket (blocking).
• int sys_tcp_recv_nb(void *buf, size_t max_len); - Receive data from a TCP socket (non-blocking).
• int sys_tcp_close(void); - Close the active TCP socket.

---

Core Data Structures

os_info_t

Contains detailed build and version information about the OS.

typedef struct {
    char os_name[64];
    char os_version[64];
    char os_codename[64];
    char kernel_name[64];
    char kernel_version[64];
    char build_date[64];
    char build_time[64];
    char build_arch[64];
} os_info_t;

FAT32_FileInfo

Represents a filesystem entry.

typedef struct {
    char name[256];
    uint32_t size;
    uint8_t is_directory;
    uint32_t start_cluster;
    uint16_t write_date;
    uint16_t write_time;
} FAT32_FileInfo;

ProcessInfo

Provides status information for an active process.

typedef struct {
    uint32_t pid;
    char name[64];
    uint64_t ticks;
    size_t used_memory;
} ProcessInfo;

IP / MAC Addresses

Wrappers for raw byte arrays.

typedef struct { uint8_t bytes[6]; } net_mac_address_t;
typedef struct { uint8_t bytes[4]; } net_ipv4_address_t;