man: document open(2)

1 files changed, 116 insertions, 0 deletions

diff --git a/man/open.2 b/man/open.2
new file mode 100644
index 0000000..3cc18b3
--- /dev/null
+++ b/man/open.2
@@ -0,0 +1,116 @@
+.Dd June 15, 2024
+.Dt OPEN 2
+.Os Camellia
+.Sh NAME
+.Nm open
+.Nd open a file
+.Sh SYNOPSIS
+.In camellia/flags.h
+.In camellia/syscalls.h
+.In camellia/types.h
+.Ft long
+.Fo _sys_open
+.Fa "const char *path"
+.Fa "long len"
+.Fa "int flags"
+.Fc
+.Sh DESCRIPTION
+.Nm
+tries to open the file located at
+.Fa path ,
+which is a string of length
+.Fa len ,
+potentially returning a new handle.
+The call will be handled by the most recent mount that contains the given path,
+according to the definition in
+.Xr path 7 .
+The path must be absolute.
+.Pp
+.Fa flags
+is a bitmask that must include
+.Sy exactly one
+of
+.Dv OPEN_READ ,
+.Dv OPEN_WRITE ,
+.Dv OPEN_RW ,
+or
+.Dv OPEN_EXEC .
+Files opened with
+.Dv OPEN_READ
+and
+.Dv OPEN_EXEC
+are read-only, and files opened with
+.Dv OPEN_WRITE
+are write-only.
+.Dv OPEN_EXEC
+only succeeds if the executable bit is set on a file.
+.Pp
+.Dv OPEN_READ
+is also meant to prevent
+.Dq major side-effects ,
+the exact meaning of which depend on the context.
+For example,
+since
+.Xr net 7
+allows connecting to any host just by opening a file,
+trying to open them as read-only returns
+.Er EACCES .
+This allows tools such as
+.Xr whitelist 1
+to reliably make an entire filesystem read-only just by
+controlling the values of
+.Fa flags
+passed to the underlying filesystems.
+.Pp
+.Fa flags
+also accepts the following additional flags:
+.Bl -tag -width OPEN_CREATE
+.It Dv OPEN_CREATE
+Try to create a new file if one isn't present at the given path.
+Requires
+.Dv OPEN_WRITE
+or
+.Dv OPEN_RW .
+.El
+.Sh RETURN VALUES
+If successful,
+.Nm
+returns a non-negative handle to the opened file.
+Otherwise, it returns a negated error value \(em
+the possible errors will depend on the filesystem.
+.Sh SEE ALSO
+.Xr fs_wait 2 ,
+.Xr mount 2 ,
+.Xr path 7
+.Sh BUGS
+No current filesystem checks the execute bit.
+.Pp
+The
+.Dq no side-effects
+aspect of
+.Dv OPEN_READ
+means that you can't
+.Dl cat /net/connect/0.0.0.0/192.0.2.1/tcp/17
+as
+.Xr cat 1
+will try to open the file as read-only and fail.
+I'm not yet sure if that's a feature or a bug.
+.Pp
+The permission flags should probably just be renamed to the POSIX ones.
+.Sh RATIONALE
+.Nm
+is the
+.Dq narrow waist
+through which all the interactions with paths are done.
+For example,
+.Xr remove 2
+only accepts a handle returned by
+.Nm ,
+instead of the full path \(em
+the same will even apply for the future move call.
+This means that all the path handling logic is concentrated in a single place.
+In particular, simple filesystem overlays such as
+.Xr whitelist 2
+only need to implement support for
+.Nm ,
+instead of needing separate logic for all calls that operate on paths.