.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.
.Fa path
can't contain any NUL bytes.
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.