# attr_multi

## 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
           elements 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 control 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 initially 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
                  privileges, 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 privileges, 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 privileges, 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_ argument.  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 component 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 {_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



           On success, zero is returned.  On error, -1 is returned, and _errno_
           is set appropriately.  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.
    


* * *