*: getxattr

1 files changed, 91 insertions, 0 deletions

diff --git a/man/getxattr.2 b/man/getxattr.2
new file mode 100644
index 0000000..d7a287e
--- /dev/null
+++ b/man/getxattr.2
@@ -0,0 +1,91 @@
+.Dd August 17, 2024
+.Dt GETXATTR 2
+.Os Camellia
+.Sh NAME
+.Nm getxattr
+.Nd get file attribute
+.Sh SYNOPSIS
+.In camellia/syscalls.h
+.Ft ssize_t
+.Fo _sys_getxattr
+.Fa "hid_t h"
+.Fa "const char *name"
+.Fa "void *buf"
+.Fa "size_t len"
+.Fa "int flags"
+.Fc
+.Sh DESCRIPTION
+.Nm
+reads the attribute of
+.Fa h
+named by
+.Fa name ,
+into
+.Fa buf .
+.Fa flags
+is reserved for future use, for now it has to be 0.
+.Pp
+The attributes can have arbitrary names of up to
+.Dv XATTRNAME_MAX
+characters, but some are explicitly defined:
+.Bl -tag -width virt.index
+.It Sy virt.index
+The list of all xattrs in arbitrary order as concatenated NUL-terminated names,
+including exactly one NUL at the end.
+.It Sy virt.mode
+The Unix file mode in octal, with or without the trailing 0.
+.It Sy virt.owner
+The Unix file owner, as either a decimal UID or an username that doesn't begin
+with a digit.
+.It Sy virt.group
+See
+.Sy virt.owner .
+.El
+.Sh RETURN VALUES
+.Nm
+returns the length of the entire attribute (which might be larger than len),
+or a negative value on failure.
+The most common errors are:
+.Bl -tag -width EGENERIC
+.It Er ENOSYS
+The filesystem doesn't support xattrs.
+.It Er ENOENT
+This xattr doesn't exist.
+.It Er EGENERIC
+The filesystem probably doesn't support xattrs,
+and it wasn't written very well.
+Sorry.
+.El
+.\" .Sh SEE ALSO
+.Sh NOTES
+The maximum size of the xattr value might become limited in the future,
+as in Linux.
+.Sh RATIONALE
+The original idea for storing metadata was something like
+Alternate Data Streams, where you'd be able to open another
+.Dq file
+that stores the metadata for any handle.
+It would either be unstructured
+.Pq gross ,
+or you'd need to open a separate file for each attribute
+.Pq slow .
+It also seemed like it would be complex to implement.
+.Pp
+A generic key-value store thing for handles also happens to seem more useful.
+I was thinking about making the API more similar to
+.Xr read 2
+and
+.Xr write 2
+with an offset argument, but that seems unnecessary.
+I don't expect the xattr values to be particularly large,
+and only allowing writes/reads of an entire xattr at once will simplify
+future attempts to add wrapper filesystems that enforce Unix-style permissions.
+This made me end up with a Linux-style interface
+.Pq thus the name .
+.Pp
+Instead of a separate syscall for listing xattrs I just use
+.Sy virt.index ,
+as that seems simpler and without any downside.
+It also lets me define paging using
+.Sy virt.index.1
+and so on, avoiding the issue Linux has with listxattrs.