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]

Reply via email to