.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
.Xr getxattr 2 .
.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.