man: start writing manpages

3 files changed, 271 insertions, 0 deletions

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 <camellia/flags.h>
+#include <camellia/syscalls.h>
+#include <camellia/types.h>
+#include <stdlib.h>
+
+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 <camellia/fs/misc.h>
+
+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.