ATTR_MULTI(3)        XFS Compatibility API        ATTR_MULTI(3)





NAME
       attr_multi,   attr_multif  -  manipulate  multiple  user
       attributes on a filesystem object at once

C SYNOPSIS
       #include <attr/attributes.h>

       int attr_multi (const char *path, attr_multiop_t *oplist,
                       int count, int flags);

       int attr_multif (int fd, attr_multiop_t *oplist,
                        int count, int flags);

DESCRIPTION
       The attr_multi and attr_multif functions provide  a  way
       to operate on multiple attributes of a filesystem object
       at once.

       Path points to a path name for a filesystem object,  and
       fd refers to the file descriptor associated with a file.
       The oplist is an  array  of  attr_multiop_t  structures.
       Each  element in that array describes a single attribute
       operation and provides all the information  required  to
       carry  out  that  operation  and to check for success or
       failure of that operation.  Count tells  how  many  ele-
       ments are in the oplist array.

       The  contents of an attr_multiop_t structure include the
       following members:

          int am_opcode; /* which operation to perform (see below) */
          int am_error; /* [out arg] result of this sub-op (an errno) */
          char *am_attrname; /* attribute name to work with */
          char *am_attrvalue; /* [in/out arg] attribute value (raw bytes) */
          int am_length; /* [in/out arg] length of value */
          int am_flags; /* flags (bit-wise OR of #defines below) */

       The am_opcode field defines how the remaining fields are
       to  be  interpreted and can take on one of the following
       values:

          ATTR_OP_GET /* return the indicated attr's value */
          ATTR_OP_SET /* set/create the indicated attr/value pair */
          ATTR_OP_REMOVE /* remove the indicated attr */

       The am_error field will contain  the  appropriate  error
       result  code  if  that  sub-operation fails.  The result
       codes for a given sub-operation  are  a  subset  of  the
       result  codes  that  are possible from the corresponding
       single-attribute function call.  For example, the result
       code  possible  from  an ATTR_OP_GET sub-operation are a
       subset of those that can be returned  from  an  attr_get
       function call.

       The  am_attrname field is a pointer to a NULL terminated
       string giving the attribute name that the  sub-operation
       should operate on.

       The am_attrvalue, am_length and am_flags fields are used
       to store the value of the named attribute, and some con-
       trol  flags for that sub-operation, respectively.  Their
       use varies depending  on  the  value  of  the  am_opcode
       field.

       ATTR_OP_GET
              The  am_attrvalue  field  is a pointer to a empty
              buffer that will be overwritten with the value of
              the named attribute.  The am_length field is ini-
              tially the total size of the memory  buffer  that
              the  am_attrvalue  field  points  to.   After the
              operation,  the  am_length  field  contains   the
              actual   size  of  the  attribute's  value.   The
              am_flags field may be set to the ATTR_ROOT  flag.
              If  the  process has appropriate priviledges, the
              ROOT namespace will be  searched  for  the  named
              attribute,  otherwise  the USER namespace will be
              searched.

       ATTR_OP_SET
              The am_attrvalue and am_length fields contain the
              new  value  for  the given attribute name and its
              length.  The ATTR_ROOT flag may  be  set  in  the
              am_flags  field.   If the process has appropriate
              priviledges, the ROOT namespace will be  searched
              for  the  named  attribute,  otherwise  the  USER
              namespace will be searched.  The ATTR_CREATE  and
              the  ATTR_REPLACE  flags  may  also be set in the
              am_flags field (but not simultaneously).  If  the
              ATTR_CREATE  flag  is set, the sub-operation will
              set the am_error field to  EEXIST  if  the  named
              attribute  already  exists.   If the ATTR_REPLACE
              flag is  set,  the  sub-operation  will  set  the
              am_error  field to ENOATTR if the named attribute
              does not already exist.  If neither of those  two
              flags  are  set and the attribute does not exist,
              then the attribute will be created with the given
              value.  If neither of those two flags are set and
              the attribute already exists, then the value will
              be replaced with the given value.

       ATTR_OP_REMOVE
              The  am_attrvalue  and  am_length  fields are not
              used and are ignored.  The am_flags field may  be
              set  to  the  ATTR_ROOT flag.  If the process has
              appropriate priviledges, the ROOT namespace  will
              be  searched  for  the named attribute, otherwise
              the USER namespace will be searched.

       The flags argument to the attr_multi  call  is  used  to
       control  following  of  symbolic links in the path argu-
       ment.  The default is to follow  symbolic  links,  flags
       should  be set to ATTR_DONTFOLLOW to not follow symbolic
       links.

       attr_multi will fail if one or more of the following are
       true:

       [ENOENT]         The named file does not exist.

       [EPERM]          The  effective  user  ID does not match
                        the owner of the file and the effective
                        user ID is not super-user.

       [ENOTDIR]        A component of the path prefix is not a
                        directory.

       [EACCES]         Search permission is denied on a compo-
                        nent of the path prefix.

       [EINVAL]         A  bit  other  than ATTR_DONTFOLLOW was
                        set in the flag argument.

       [EFAULT]         Path,  or  oplist  points  outside  the
                        allocated address space of the process.

       [ELOOP]          A path name lookup  involved  too  many
                        symbolic links.

       [ENAMETOOLONG]   The   length   of  path  exceeds  {MAX-
                        PATHLEN}, or a  pathname  component  is
                        longer than {MAXNAMELEN}.

       attr_multif will fail if:

       [EINVAL]       A bit was set in the flag argument, or fd
                      refers to a socket, not a file.

       [EFAULT]       Oplist  points  outside   the   allocated
                      address space of the process.

       [EBADF]        Fd  does not refer to a valid descriptor.

DIAGNOSTICS
       On success, zero is returned.  On error, -1 is returned,
       and  errno is set appropriately.  Note that the individ-
       ual operations listed in  the  oplist  array  each  have
       their  own error return fields.  The errno variable only
       records the result of the attr_multi  call  itself,  not
       the result of any of the sub-operations.

SEE ALSO
       attr(1), attr_get(3), attr_remove(3), and attr_set(3).



Dec 2001              Extended Attributes         ATTR_MULTI(3)
