From 88726ea9830c7213a7d9c1965eba97d3987b87d5 Mon Sep 17 00:00:00 2001 From: dzwdz Date: Sat, 25 May 2024 21:43:13 +0200 Subject: man: start writing manpages --- man/fork.2 | 71 ++++++++++++++++++++++++++++++++++++++ man/mount.2 | 87 ++++++++++++++++++++++++++++++++++++++++++++++ man/net.7 | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 271 insertions(+) create mode 100644 man/fork.2 create mode 100644 man/mount.2 create mode 100644 man/net.7 (limited to 'man') diff --git a/man/fork.2 b/man/fork.2 new file mode 100644 index 0000000..97b0f8a --- /dev/null +++ b/man/fork.2 @@ -0,0 +1,71 @@ +.Dd May 20, 2024 +.Dt FORK 2 +.Os Camellia +.Sh NAME +.Nm fork +.Nd copy the current process +.Sh SYNOPSIS +.In camellia/flags.h +.In camellia/syscalls.h +.In camellia/types.h +.Ft long +.Fo _sys_fork +.Fa "int flags" +.Fa "hid_t *fs_front" +.Fc +.Sh DESCRIPTION +.Nm +creates a copy of the current process and schedules it for execution. +.Pp +.Fa flags +is a bitmask, with the following options: +.Bl -tag -width FORK_SHAREHANDLE +.It Dv FORK_SHAREMEM +Share the parent's pagetable with the child. +If this flag is not passed, +the entire address space of the parent is copied (no CoW yet). +Any new memory allocations will be reflected in both processes. +.It Dv FORK_SHAREHANDLE +Share the parent's handle set with the child. +The effects of +.Xr open 2 , +.Xr close 2 , +etc. will be reflected in both processes. +.It Dv FORK_NOREAP +Ignore the child in future +.Xr wait2 2 +calls. +It will be automatically reaped on death, +without waiting for the parent to take action. +.It Dv FORK_NEWFS +Make the child responsible for a new filesystem, +and put its corresponding handle in +.Fa *fs_front . +The handle can then be passed to +.Xr mount 2 . +.El +.Pp +.Fa fs_front +is ignored, +unless +.Dv FORK_NEWFS +is specified. +It should be +.Dv NULL +otherwise. +.Sh RETURN VALUES +When successful, +.Nm +returns 0 in the child, +and the child's PID in the parent. +When not succesful, it returns one of the following (negated) errors: +.Bl -tag -width EMFILE +.It Er EMFILE +.Dv FORK_NEWFS +was specified and there's no handles left in the parent. +.El +.Sh SEE ALSO +.Xr exit 2 , +.Xr getpid 2 , +.Xr getprocfs 2 , +.Xr wait2 2 diff --git a/man/mount.2 b/man/mount.2 new file mode 100644 index 0000000..d94bf8d --- /dev/null +++ b/man/mount.2 @@ -0,0 +1,87 @@ +.Dd May 21, 2024 +.Dt MOUNT 2 +.Os Camellia +.Sh NAME +.Nm mount +.Nd mount a filesystem +.Sh SYNOPSIS +.In camellia/syscalls.h +.In camellia/types.h +.Ft long +.Fo _sys_mount +.Fa "hid_t hid" +.Fa "const char *mpoint" +.Fa "long len" +.Fc +.Sh DESCRIPTION +.Nm +mounts the filesystem pointed to by +.Fa hid +at +.Fa mpoint , +which is a string of length +.Fa len . +Unless overridden by a future +.Nm mount , +all +.Xr open 2 +calls under that path in the current process +will be handled by the chosen filesystem. +Other processes are unaffected \(em +in particular, children forked off before the mount call retain their old view +of the filesystem. +.Pp +The filesystem handle, +.Fa hid , +can come from a +.Xr fork 2 +call with the +.Dv FORK_NEWFS +flag, or from +.Xr getprocfs 2 . +If the handle isn't a valid filesystem, all +.Xr open 2 +calls under +.Fa mpoint +will fail. +This can be used to deny access to a path \(em +for that purpose, you can use a +.Fa hid +of -1, which will never be a valid handle. +.Sh EXAMPLES +To mount a child under a path: +.Bd -literal -offset indent +#include +#include +#include +#include + +hid_t h; +if (_sys_fork(FORK_NEWFS, &h) == 0) { // lacks error checking! + do_child_stuff(); + exit(1); +} +_sys_mount(h, "/path/", strlen("/path")); +.Ed +.Pp +However, ideally you'd use the +.Xr MOUNT_AT 3 +macro instead: +.Bd -literal -offset indent +#include + +MOUNT_AT("/path/") { + do_child_stuff(); + // will automatically exit() if do_child_stuff() returns +} +.Ed +.Pp +To deny access to a path, you can run +.Bd -literal -offset indent +_sys_mount(-1, path, strlen(path)); +.Ed +.Sh SEE ALSO +.Xr fork 2 , +.Xr getprocfs 2 , +.Xr open 2 , +.Xr path 7 diff --git a/man/net.7 b/man/net.7 new file mode 100644 index 0000000..0f8c360 --- /dev/null +++ b/man/net.7 @@ -0,0 +1,113 @@ +.Dd May 21, 2024 +.Dt NET 7 +.Os Camellia +.Sh NAME +.Nm net +.Nd the network interface +.Sh DESCRIPTION +Networking in Camellia is handled via a structured filesystem, +usually mounted at +.Pa /net/ , +the details of which are explained here. +.Ss Making outbounds connections +Outbounds connection are made by opening +.Pa /net/connect/SRC/DST/PROTO/PORT . +.Pp +.Ql SRC +and +.Ql DST +refer to network addresses \(em +.Xr netstack 4 +currently only supports IPv4 addresses in the +.Xr inet_aton 3 +format, but e.g.\& +.Xr socksfs 4 +supports using domain names as destinations too. +If a program doesn't care which interface is used to send the packet, +.Ql SRC +should be set to +.Ql 0.0.0.0 . +.Ql PROTO +is either +.Ql tcp +or +.Ql udp , +and +.Ql PORT +is the port. +.Pp +For example, opening +.Pa /net/connect/0.0.0.0/192.0.2.1/tcp/80 +will make a connection to 192.0.2.1, +on TCP port 80, +using any interface (0.0.0.0). +.Pp +If using TCP, +the +.Xr open 2 +call will block until the connection succeeds or fails. +Timeouts aren't currently implemented. +The received handle can be directly read and written to. +.Pp +The file must be opened in read-write mode for a connection to be made. +If +.Dv OPEN_RW +isn't set, the open call won't succeed. +.Ss Listening for incoming connections +Opening +.Pa /net/listen/ADDR/PROTO/PORT +blocks until a connection is received, or until an error. +The meanings of the path components are the same as for outbounds connections, +and the received handle can also be directly read and written to. +.Ss Other paths +.Xr netstack 4 +exposes a few other files in +.Pa /net/ : +.Bl -tag -width /net/raw -offset 2 -compact +.It Pa /net/raw +When read, listens for the next Ethernet packet. +When written, sends a Ethernet packet. +.It Pa /net/arp +Contains the ARP cache. +Read-only. +.El +.Pp +They're implementation details and should not be relied on. +.Ss Other interfaces +.Xr root 4 +provides +.Pa /dev/eth , +which is used by +.Xr netstack 4 +to interface with the NIC. +That path should be inaccessible to unprivileged programs. +.Pp +Apart from that, +.Pa /net/ +is the only way to access the network \(em +which means that the standard filesystem security tools can be used to restrict +network access. +.Pp +The traditional +.Xr socket 3 +interface is emulated by the libc. +.Sh EXAMPLES +.Xr netdog 1 +can be used to make connections from the command line. +.Dl $ netdog /net/connect/0.0.0.0/192.0.2.1/tcp/80 +.Dl $ netdog /net/listen/0.0.0.0/tcp/80 +.Xr cat 1 +won't work, because it tries to open the file as read-only. +.Pp +.Xr whitelist 4 +can be used as a very barebones firewall. +.Dl $ whitelist /bin/httpd:ro /net/listen/0.0.0.0/tcp/80 /usr/www/:ro -- httpd +.Dl $ whitelist /bin/curl:ro /net/connect/0.0.0.0/192.0.2.1/ -- curl 192.0.2.1 +.Sh SEE ALSO +.Xr curl 1 , +.Xr netdog 1 , +.Xr netstack 4 , +.Xr socksfs 4 +.Sh BUGS +There's currently no way to get metadata about the connection, +such as the local and remote IPs. -- cgit v1.2.3