Hello everybody,
this is my third push towards evolving the extended attributes system call
interface to something that is acceptable for inclusion into the standard
kernel :-) I've tried to write things up as a manual page. The source and
a pdf version can be found at <http://acl.bestbits.at/pre/>.
A mostly finished implementation for ext2 of the EA interface documented
here, and of ACLs on top of it, is almost finished. I'm planning to solve
the remaining quircks this weekend, so perhaps I can post a link tomorrow.
Everybody, please do comment on this proposal, and point me at things that
I've missed. I know there are a couple of issues we need to discuss...
Regards,
Andreas.
------------------------------------------------------------------------
Andreas Gruenbacher, [EMAIL PROTECTED]
Contact information: http://www.bestbits.at/~ag/
Manual page
-----------
EXT_ATTR(2) Extended attributes EXT_ATTR(2)
NAME
ext_attr_path, ext_attr_fd - manipulate extended
attributes
SYNOPSIS
#include <sys/types.h>
#include <linux/ext_attr.h>
int ext_attr_path(const char *path, struct
ext_attr_operation *ops, size_t ops_size, int flags);
int ext_attr_fd(int fd, struct ext_attr_operation *ops,
size_t ops_size, int flags);
DESCRIPTION
This manual page documents the extended attribute system
call interface of Linux as implemented by the patch found
at http://acl.bestbits.at/ (ea2 / acl2 versions).
Extended attributes are name/value pairs associated with
inodes (regular and special files, directories). Each
inode is associated with a set of extended attributes. The
name of an extended attribute consists of an namespace
qualifier and a name string. The value of an extended
attribute is a chunk of arbitrary textual or binary data
of specified length.
The namespace mechanism is used to define different
classes of extended attributes. These classes mainly dif-
fer in the permissions and capabilities required for
manipulating extended attributes. The following namespaces
are defined (list access to an attribute means the
attribute is included in extended attribute name lists of
EXT_ATTR_LIST operations).
EXT_ATTR_NSP_USER ("user")
Extended user attributes are subject to the same
restrictions as the contents of the file they are
associated with. Processes with read or write access
have list access to extended user attributes. Read
access to the file also implies read access to
extended user attributes. Write access to the file
implies create, modify and delete access to extended
user attributes. Character and block device special
files have no extended user attributes.
EXT_ATTR_NSP_INODE ("inode")
Extended inode attributes are subject to the same
restrictions as the traditional attributes of the file
(timestamps, file mode permission bits). Processes
with search access (i.e., read access to the directory
the file is contained in) have list and read access to
extended inode attributes. The file owner and pro-
cesses capable of CAP_FOWNER are allowed to create,
modify and delete extended inode attributes.
EXT_ATTR_NSP_TRUSTED ("trusted")
All accesses to trusted extended attributes require
the CAP_TRUSTED capability. Processes without that
capability have neither list, read nor create, modify
or delete access. This namespace is intended to be
used by trusted subsystems of the kernel that run in
user space, and which need to store sensitive
attributes.
EXT_ATTR_NSP_ACL_POSIX ("acl_posix")
This namespace is used for storing POSIX access con-
trol lists (ACLs). The permissions required are simi-
lar to extended attributes. In addition, the validity
of ACLs is checked when creating/modifying them. This
will be discussed separately.
The ext_attr_path() and ext_attr_fd() system calls manipu-
late the extended attributes of a file by carrying out a
sequence of operations on them. The path and fd parameters
specify the file name and the file descriptor of the file
whose extended attributes shall be manipulated. The ops
array specifies a sequence of operations to be performed.
The ops_size parameter specifies the size of the ops array
in bytes. The flags parameter specifies a bitwise combina-
tion of additional flags that influence the behavior of
the system calls (the default value is 0; see the
EXT_ATTR_FLAG_* definitions below).
The operations in the ops array are executed in sequence.
The result of each operation is stored in the result
field. If an operation fails, the EXT_ATTR_FLAG_IGN_ERR
flag of the system calls specifies whether the following
operations are executed or not. Each operation in the ops
array contains at least the following fields.
struct ext_attr_operation {
int operation;
int flags;
int namespce;
unsigned int name_len;
const char *name;
size_t buffer_size;
void *buffer;
int result;
};
operation
The operation to be performed. A list of possible
operations is given below.
flags
A bitwise combination of EXT_ATTR_OP_FLAG_* flags that
influence how this particular operation is carried out
(not to be confused with the system call flags, which
are called EXT_ATTR_FLAG_*.)
namespce
The namespace of the extended attribute, e.g.,
EXT_ATTR_NSP_USER. This field is ignored if the spec-
ified operation affects multiple extended attributes.
name_len
The length of the name of the extended attribute.
This field is ignored if the specified operation
affects multiple extended attributes.
name
The name of the extended attribute. This field is
ignored if the specified operation affects multiple
extended attributes.
buffer_size
The size of the buffer field in bytes. This field is
also used to return the required size and actual
length of the value in buffer.
buffer
The buffer for passing values in and out. Lists of
extended attribute names are also returned in this
buffer. This field may be NULL to indicate that there
is no value, or that the value is not of interest to
the caller.
result
The result of the extended attribute operation is
stored here. Negative values indicate system errors
codes. Non-negative values indicate success.
EXTENDED ATTRIBUTE OPERATIONS
EXT_ATTR_OP_GET
Fetch the value of the extended attribute named name
in namespace namespce into the buffer. This operation
stores the length of the attribute value in
buffer_size. If the buffer is too small to hold the
value, result is set to -ERANGE. If buffer is NULL, 0
is returned.
EXT_ATTR_OP_SET
Create a new extended attribute, or overwrite the
value of the extended attribute name in namespace
namespce with the new value in buffer of size
buffer_size. If buffer is NULL, remove the extended
attribute with that name. The two flags
EXT_ATTR_OP_FLAG_EXISTS and EXT_ATTR_OP_FLAG_CREATE
can be used to influence this operation. See below.
EXT_ATTR_OP_LIST
This operation returns a list of extended attribute
names. The names are stored in the buffer of size
buffer_size as ext_attr_entry records. If the list of
names does not fit within buffer_size bytes, result is
set to -ERANGE. If this operation is immediately pre-
ceded by an EXT_ATTR_OP_LIST_CURSOR operation, as many
names are returned as possible, and the cursor is
updated so that the next call returns the next batch
of names. If buffer is NULL for this operation,
buffer_size is set to a reasonable value for the
buffer size. The result field is set to the number of
entries returned in buffer. If a list cursor is used,
the result value of the EXT_ATTR_OP_LIST_CURSOR opera-
tion is set to 0 if there are no more names in the
list, and to a value greater than 0 if there may be
more names in the list.
EXT_ATTR_OP_LIST_CURSOR
This operation is used to implement resumable list
operations. The kernel is provided with a buffer in
which it stores a cursor into the list of extended
attribute names of an inode. This cursor is passed to
the kernel between system calls, so that the kernel
can return long extended attribute lists in parts. The
buffer is initialized to zeroes to receive the first
part of the list. If the buffer field is NULL, this
operation returns the required buffer size for the
cursor in the buffer_sizefield.
EXT_ATTR_OP_GET_COOKIE
This operation returns an opaque cookie in buffer that
represents the current "version" of the extended
attributes. The version changes whenever the set of
extended attributes of that inode changes. If the
buffer field is NULL, this operation returns the
required buffer size for the cookie. This operation is
used to prevent race conditions between related
extended attribute system calls. This operation is not
supported by all filesystems.
EXT_ATTR_OP_VERIFY_COOKIE
This operation compares the cookie in buffer with the
current cookie of the inode. The operation succeeds
with a result of 0 if the two cookies are identical,
and fails with -EAGAIN in result if the cookies dif-
fer. This operation is not supported by all filesys-
tems.
EXT_ATTR_OP_VERIFY
This operation compares the current value of the
extended attribute name in namespace namespce with the
value in buffer. The operation fails with a result of
-EAGAIN if the current value differs from the value in
buffer. Otherwise, the operation succeeds with a
result of 0.
SYSTEM CALL AND OPERATION FLAGS
There are the currently defined system call flags.
EXT_ATTR_FLAG_NOFOLLOW
If the last component of path is a symbolic link, the
ext_attr_path() system call fails. Symbolic links in
earlier components of the pathname are still followed.
EXT_ATTR_FLAG_SYNC
Write extended attributes to disk with synchronous
I/O.
EXT_ATTR_FLAG_IGN_ERR
Ignore errors in extended attribute operations. The
default behavior is to stop at the first error in ops.
With this flag set, the sequence of operations is
fully executed, even if some operations fail.
EXT_ATTR_FLAG_ISOLATED
Execute all operations in the ops array in one logical
step. Intermediate results are not visible to other
processes. Some filesystems (e.g., NFS) can/may not
implement this. On some filesystems this flag may be
implicit.
EXT_ATTR_FLAG_ATOMIC
Execute all operations in ops, or execute none.
Filesystems are not required to support this flag.
There are the currently defined extended attribute opera-
tion flags.
EXT_ATTR_OP_FLAG_EXISTS
The operation only succeeds if the named extended
attribute exists. If it does not exist, result is set
to -ENOATTR.
EXT_ATTR_OP_FLAG_CREATE
The operation will only succeed if the named extended
attribute does not exist. If it does exist, result is
set to -EEXIST.
LIST OPERATIONS
The list of extended attribute names for an inode can be
retrieved in a single system call, or it can be retrieved
in multiple parts in multiple subsequent system calls. In
at-once mode, a sufficiently large buffer must be passed
to the kernel to hold the complete list. In resumable
mode, the buffer must be sufficiently large to hold the
next batch of names only.
Since the kernel does not internally store state between
extended attribute system calls, the EXT_ATTR_OP_LIST_CUR-
SOR operation is used to provide the kernel with a buffer
in which to store a list cursor. EXT_ATTR_OP_LIST_CURSOR
operations must immediately precede the corresponding
EXT_ATTR_OP_LIST operations. The list of names is returned
in at-once mode if an EXT_ATTR_OP_LIST operation is not
immediately preceded by an EXT_ATTR_OP_LIST_CURSOR opera-
tion.
The buffer passed to EXT_ATTR_OP_LIST_CURSOR is zero ini-
tialized to retrieve the first batch of extended attribute
names. The kernel advances the value in this buffer in
each system call to point to the next batch of names. The
cursor value itself is opaque to the calling process, and
may become invalid if the process issues another indepen-
dent extended attribute system call during a resumable
list operation, or terminates.
The result of the EXT_ATTR_OP_LIST_CURSOR operation indi-
cates when the end of the extended attribute name list has
been reached (see the description of the
EXT_ATTR_OP_LIST_CURSOR operation above).
All filesystems must implement both list modes. A filesys-
tem may require a certain buffer size. This buffer size
must be returned by the EXT_ATTR_OP_LIST operation if
buffer is NULL. (The idea behind is to allow filesystem
block size resolution of the cursor---if the buffer has a
certain size, all names on a disk block fit in the buffer,
so the cursor advances by one block each system call.) A
filesystem may decide to return the complete list of names
at once by demanding a sufficiently large buffer for
EXT_ATTR_OP_LIST.
NOTE: Maybe it makes sense to drop at-once mode com-
pletely?
The list of names is returned as an array of variable-size
entries of type struct ext_attr_entry in the buffer of the
EXT_ATTR_OP_LIST operation, similar to struct dirent in
<dirent.h>. The record_len field of each entry contains
the length of the entry in bytes, including the namespace.
The name_len field contains the length of the extended
attribute name.
struct ext_attr_entry {
int namespce;
unsigned short record_len;
unsigned short name_len;
char name[0];
};
AVOIDING RACE CONDITIONS
Sometimes it is necessary to read extended attribute val-
ues in one system call, perform some update operation, and
write back the updated values. When two such update opera-
tions overlap, some results may be lost. (Extended
attributes cannot be locked to serialize such updates.
Locking would require tracking state, which we want to
avoid.) Race conditions can be avoided using one of two
approaches.
Approach one: Cookies
The extended attributes to be updated are read using one
EXT_ATTR_OP_GET_COOKIE operation followed by one or more
EXT_ATTR_OP_GET operations. The values are updated by the
process. Then, the values are written back in a single
isolated system call (flag EXT_ATTR_FLAG_ISOLATED) with
one EXT_ATTR_OP_VERIFY_COOKIE operation followed by one or
more EXT_ATTR_OP_SET operations. The cookie from the first
system call is passed to the second. The EXT_ATTR_OP_VER-
IFY_COOKIE operation fails if the set of extended
attributes has been changed by another process in between.
The EXT_ATTR_FLAG_ISOLATED flag ensures other processes
don't see any intermediary states.
Approach two: Comparing values
The extended attributes to be updated are read using one
or more EXT_ATTR_GET operations. The old values are
copied, and the copies are updated. Then, the values are
updated in a single isolated system call (flag
EXT_ATTR_FLAG_ISOLATED) with one EXT_ATTR_OP_VERIFY opera-
tion for each attribute (with the original attribute
value), followed by one EXT_ATTR_OP_SET operation for each
attribute that is to be updated (with the new attribute
value).
QUESTION: What is the benefit of EXT_ATTR_OP_VERIFY for
NFS as compared to issuing two separate RPC's (read and
then write)? NFS neither supports isolated semantics or
cookies. Local filesystems can always support the cookie
approach, which is more efficient, too.
DIFFERENCES AMONG FILESYSTEMS
Different filesystems may impose arbitrary limitations on
the length on extended attribute names or values, on the
number of extended attributes allowed for a single inode,
on the total size consumed for extended attributes for an
inode, etc. Some extended attribute namespaces may not be
supported, and additional namespaces may exist. The fol-
lowing features mentioned on this manual page may be miss-
ing in some implementations:
o The EXT_ATTR_NSP_ACL_POSIX namespace.
o At-once list mode.
o The EXT_ATTR_OP_GET_COOKIE and EXT_ATTR_OP_VER-
IFY_COOKIE operations.
o The EXT_ATTR_OP_VERIFY operation.
o The EXT_ATTR_FLAG_ISOLATED and/or EXT_ATTR_FLAG_ATOMIC
flags.
o The EXT_ATTR_OP_FLAG_EXISTS and/or
EXT_ATTR_OP_FLAG_CREATE operation flags.
EXAMPLES
RETURN VALUE
On success, the number of operations processed is
returned. If an error occurs accessing the file, -1 is
returned, and errno is set appropriately.
If an error occurs in an operation, the result field of
the operation is set to a negative system error code
("-errno"). If an operation succeeds, the result field of
the operation is set to 0, unless otherwise noted.
The results for individual operations are as follows.
EXT_ATTR_OP_GET
If the named attribute does not exist, or the process
has no access to this attribute, result is set to
-ENOATTR.
EXT_ATTR_OP_SET
If the EXT_ATTR_OP_FLAG_CREATE flag is given and the
attribute exists already, result is set to -EEXIST.
If the EXT_ATTR_OP_FLAG_EXISTS flag is given and the
attribute does not exist, result is set to -ENOATTR.
If there is not enough space left to store the
extended attribute, result is set to -ENOSPC.
EXT_ATTR_OP_LIST_CURSOR
If this operation returns the last batch of names for
this inode, result is set to 0. If there may be more
names following this batch, result is set to 1.
EXT_ATTR_OP_VERIFY_COOKIE
If the cookie passed in buffer doesn't match the
inode's current cookie, result is set to -EAGAIN.
EXT_ATTR_OP_VERIFY
If the value in buffer does not match the current
value, result is set to -EAGAIN.
OTHER COMMON ERRORS
ERANGE The attribute name is too long. The attribute
value is too long. The buffer is too small to hold
the result.
ENOTSUP Extended attributes are not supported by this
filesystem. This operation is not supported on
this filesystem. This operation is not enabled on
this filesystem.
ENOATTR The named extended attribute does not exist.
EEXIST The named extended attribute already exists.
ENOSPC No space is left for storing the extended
attributes.
AUTHOR
Andreas Gruenbacher, <[EMAIL PROTECTED]>.
Please send your bug reports and comments to the above
address.
SEE ALSO
ext_attr(5)
-
To unsubscribe from this list: send the line "unsubscribe linux-fsdevel" in
the body of a message to [EMAIL PROTECTED]