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  aattttrr_mmuullttiioopp_tt  structures.   Each
       element  in that array describes a single attribute opera­
       tion 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 elements are in  the
       oplist array.

       The  contents  of  an aattttrr_mmuullttiioopp_tt structure include the
       following members:

          iinntt aamm_ooppccooddee;; //** wwhhiicchh ooppeerraattiioonn ttoo ppeerrffoorrmm ((sseeee bbeellooww)) **//
          iinntt aamm_eerrrroorr;; //** [[oouutt aarrgg]] rreessuulltt ooff tthhiiss ssuubb--oopp ((aann eerrrrnnoo)) **//
          cchhaarr **aamm_aattttrrnnaammee;; //** aattttrriibbuuttee nnaammee ttoo wwoorrkk wwiitthh **//
          cchhaarr **aamm_aattttrrvvaalluuee;; //** [[iinn//oouutt aarrgg]] aattttrriibbuuttee vvaalluuee ((rraaww bbyytteess)) **//
          iinntt aamm_lleennggtthh;; //** [[iinn//oouutt aarrgg]] lleennggtthh ooff vvaalluuee **//
          iinntt aamm_ffllaaggss;; //** ffllaaggss ((bbiitt--wwiissee OORR ooff ##ddeeffiinneess bbeellooww)) **//

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

          AATTTTRR_OOPP_GGEETT //** rreettuurrnn tthhee iinnddiiccaatteedd aattttrr''ss vvaalluuee **//
          AATTTTRR_OOPP_SSEETT //** sseett//ccrreeaattee tthhee iinnddiiccaatteedd aattttrr//vvaalluuee ppaaiirr **//
          AATTTTRR_OOPP_RREEMMOOVVEE //** rreemmoovvee tthhee iinnddiiccaatteedd aattttrr **//

       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  AATTTTRR_OOPP_GGEETT  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

       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  AATTTTRR_RROOOOTT flag.  If the process has appro­
              priate 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 AATTTTRR_RROOOOTT  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 names­
              pace will be searched.   The  AATTTTRR_CCRREEAATTEE  and  the
              AATTTTRR_RREEPPLLAACCEE  flags may also be set in the am_flags
              field (but not simultaneously).  If the AATTTTRR_CCRREEAATTEE
              flag   is  set,  the  sub-operation  will  set  the
              am_error field to EEXIST  if  the  named  attribute
              already  exists.   If the AATTTTRR_RREEPPLLAACCEE 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 AATTTTRR_RROOOOTT flag.  If the process has appropriate
              priviledges, the ROOT namespace  will  be  searched
              for  the named attribute, otherwise the USER names­
              pace will be searched.

       The flags argument to the attr_multi call is used to  con­
       trol  following  of  symbolic  links in the path argument.
       The default is to follow symbolic links, flags  should  be


       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 allo­
                        cated address space of the process.

       [ELOOP]          A path name lookup involved too many sym­
                        bolic links.

       [ENAMETOOLONG]   The  length of path exceeds {MAXPATHLEN},
                        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

       Upon successful completion of the attr_multi call, a value
       of 0 is returned.  Otherwise, a value of  -1  is  returned
       and  errno  is  set  to indicate the error.  Note that the
       individual 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).


Man(1) output converted with man2html