<div align="center">
  <h1>Userland SDK Reference</h1>
  <p><em>Comprehensive manual for custom libc and system calls in BoredOS.</em></p>
</div>

---

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.

```c
#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.
```c
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.
```c
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.
```c
typedef struct {
    uint32_t pid;
    char name[64];
    uint64_t ticks;
    size_t used_memory;
} ProcessInfo;
```

### IP / MAC Addresses
Wrappers for raw byte arrays.
```c
typedef struct { uint8_t bytes[6]; } net_mac_address_t;
typedef struct { uint8_t bytes[4]; } net_ipv4_address_t;
```
