boredos_mirror/docs/appdev/syscalls.md

Syscall Reference

This page documents the current syscall surface in BoredOS as implemented in:

• src/sys/syscall.h (kernel command IDs)
• src/userland/libc/syscall.h (userland wrappers)

Use libc wrappers when possible instead of calling raw syscall numbers directly.

Top-Level Syscall Numbers

Number	Name	Purpose
0	SYS_EXIT (userland header)	Terminate current process
1	SYS_WRITE	Write to stdout/tty path
3	SYS_GUI	Window manager and drawing commands
4	SYS_FS	Filesystem and fd commands
5	SYS_SYSTEM	System-wide command multiplexer
9	SYS_SBRK (userland header)	Heap break management
10	SYS_KILL (userland header)	Kill process by PID
60	SYS_EXIT (kernel header)	Internal kernel syscall number map

Notes:

• Some numbers differ between kernel and userland headers for historical reasons. For app code, rely on wrapper functions in src/userland/libc/syscall.c.
• SYS_GUI, SYS_FS, and SYS_SYSTEM are command multiplexers.

FS Command IDs (SYS_FS)

ID	Macro	Meaning
1	FS_CMD_OPEN	Open file
2	FS_CMD_READ	Read from fd
3	FS_CMD_WRITE	Write to fd
4	FS_CMD_CLOSE	Close fd
5	FS_CMD_SEEK	Seek in file
6	FS_CMD_TELL	Current offset
7	FS_CMD_LIST	Directory listing
8	FS_CMD_DELETE	Delete file
9	FS_CMD_SIZE	File size
10	FS_CMD_MKDIR	Create directory
11	FS_CMD_EXISTS	Path exists check
12	FS_CMD_GETCWD	Get cwd
13	FS_CMD_CHDIR	Change cwd
14	FS_CMD_GET_INFO	File metadata
15	FS_CMD_DUP	dup fd
16	FS_CMD_DUP2	dup2 fd
17	FS_CMD_PIPE	Create pipe
18	FS_CMD_FCNTL	fcntl flags ops

SYSTEM Command IDs (SYS_SYSTEM)

Desktop and display

ID	Macro	Meaning
1	SYSTEM_CMD_SET_BG_COLOR	Set desktop background color
2	SYSTEM_CMD_SET_BG_PATTERN	Set desktop background pattern
3	SYSTEM_CMD_SET_WALLPAPER	Legacy wallpaper command slot
4	SYSTEM_CMD_SET_DESKTOP_PROP	Set desktop behavior property
5	SYSTEM_CMD_SET_MOUSE_SPEED	Set mouse speed
7	SYSTEM_CMD_GET_DESKTOP_PROP	Get desktop property
8	SYSTEM_CMD_GET_MOUSE_SPEED	Get mouse speed
9	SYSTEM_CMD_GET_WALLPAPER_THUMB	Legacy wallpaper thumb slot
10	SYSTEM_CMD_CLEAR_SCREEN	Clear text console
29	SYSTEM_CMD_SET_TEXT_COLOR	Set console text color
31	SYSTEM_CMD_SET_WALLPAPER_PATH	Set wallpaper from path
40	SYSTEM_CMD_SET_FONT	Set active font
47	SYSTEM_CMD_SET_RESOLUTION	Set display mode

Time, power, and system state

ID	Macro	Meaning
11	SYSTEM_CMD_RTC_GET	Read RTC datetime
12	SYSTEM_CMD_REBOOT	Reboot machine
13	SYSTEM_CMD_SHUTDOWN	Power off machine
14	SYSTEM_CMD_BEEP	PC speaker beep
15	SYSTEM_CMD_GET_MEM_INFO	Return total/used memory
16	SYSTEM_CMD_GET_TICKS	Return scheduler/WM tick count
28	SYSTEM_CMD_GET_SHELL_CONFIG	Read shell config value
32	SYSTEM_CMD_RTC_SET	Set RTC datetime
41	SYSTEM_CMD_SET_RAW_MODE	Terminal raw-mode control
43	SYSTEM_CMD_YIELD	Yield scheduler timeslice
46	SYSTEM_CMD_SLEEP	Sleep current process

Network

ID	Macro	Meaning
6	SYSTEM_CMD_NETWORK_INIT	Init networking
17	SYSTEM_CMD_PCI_LIST	PCI device list access
18	SYSTEM_CMD_NETWORK_DHCP	DHCP acquire
19	SYSTEM_CMD_NETWORK_GET_MAC	Read NIC MAC
20	SYSTEM_CMD_NETWORK_GET_IP	Read IPv4
21	SYSTEM_CMD_NETWORK_SET_IP	Set static IPv4
22	SYSTEM_CMD_UDP_SEND	Send UDP packet
23	SYSTEM_CMD_NETWORK_GET_STATS	Network stats
24	SYSTEM_CMD_NETWORK_GET_GATEWAY	Read gateway
25	SYSTEM_CMD_NETWORK_GET_DNS	Read DNS server
26	SYSTEM_CMD_ICMP_PING	ICMP ping
27	SYSTEM_CMD_NETWORK_IS_INIT	Network initialized flag
30	SYSTEM_CMD_NETWORK_HAS_IP	Has IPv4 address flag
33	SYSTEM_CMD_TCP_CONNECT	TCP connect
34	SYSTEM_CMD_TCP_SEND	TCP send
35	SYSTEM_CMD_TCP_RECV	TCP recv (blocking)
36	SYSTEM_CMD_TCP_CLOSE	TCP close
37	SYSTEM_CMD_DNS_LOOKUP	DNS lookup
38	SYSTEM_CMD_SET_DNS	Set DNS server
39	SYSTEM_CMD_NET_UNLOCK	Force net lock release
42	SYSTEM_CMD_TCP_RECV_NB	TCP recv (non-blocking)
48	SYSTEM_CMD_NETWORK_GET_NIC_NAME	NIC name

Process, tty, signals

ID	Macro	Meaning
50	SYSTEM_CMD_PARALLEL_RUN	Dispatch parallel job
60	SYSTEM_CMD_TTY_CREATE	Create tty
61	SYSTEM_CMD_TTY_READ_OUT	Read tty output buffer
62	SYSTEM_CMD_TTY_WRITE_IN	Write tty input buffer
63	SYSTEM_CMD_TTY_READ_IN	Read input for current tty
64	SYSTEM_CMD_SPAWN	Spawn process
65	SYSTEM_CMD_TTY_SET_FG	Set tty foreground PID
66	SYSTEM_CMD_TTY_GET_FG	Get tty foreground PID
67	SYSTEM_CMD_TTY_KILL_FG	Kill tty foreground PID
68	SYSTEM_CMD_TTY_KILL_ALL	Kill tty process group
69	SYSTEM_CMD_TTY_DESTROY	Destroy tty
70	SYSTEM_CMD_EXEC	Exec replace current process
71	SYSTEM_CMD_WAITPID	Wait/reap child
72	SYSTEM_CMD_KILL_SIGNAL	Send signal
73	SYSTEM_CMD_SIGACTION	Set/get handler
74	SYSTEM_CMD_SIGPROCMASK	Signal mask ops
75	SYSTEM_CMD_SIGPENDING	Get pending signals

ELF app metadata

ID	Macro	Meaning
76	SYSTEM_CMD_GET_ELF_METADATA	Read full app metadata from an ELF
77	SYSTEM_CMD_GET_ELF_PRIMARY_IMAGE	Read primary icon path from an ELF

Common Wrapper API (src/userland/libc/syscall.h)

Typical wrappers used by apps:

• Process/system: sys_exit, sys_yield, sys_spawn, sys_exec, sys_waitpid, sys_kill_signal
• Filesystem: sys_open, sys_read, sys_write_fs, sys_close, sys_seek, sys_tell, sys_size, sys_list
• Network: sys_network_init, sys_network_dhcp_acquire, sys_udp_send, sys_tcp_connect, sys_tcp_recv_nb, sys_dns_lookup
• TTY: sys_tty_create, sys_tty_read_out, sys_tty_write_in, sys_tty_set_fg
• ELF metadata: sys_get_elf_metadata, sys_get_elf_primary_image — see elf_metadata.md for full usage

Best Practices

• Do not hardcode numeric command IDs in app code.
• Prefer high-level libc calls (open, read, waitpid, sigaction) where available.
• Use syscall.h macros when a raw sys_system call is still needed.