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/mount.2 | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 man/mount.2

(limited to 'man/mount.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
-- 
cgit v1.2.3