PARAMETERS

Input

An opaque handle bound to a registry server. Use
sec_rgy_site_open() to acquire a bound handle.

name_domain

A value of type sec_rgy_domain_t that identifies the registry
domain in which the object specified by name resides. The valid
values are as follows:

sec_rgy_domain_person

The name identifies a principal.

sec_rgy_domain_group

The name identifies a group.

sec_rgy_domain_org

The name identifies an organization.

This parameter is ignored if name is policy or replist.

name

A character string of type sec_rgy_name_t specifying the name
of the person, group, or organization to which the attribute is attached.

num_to_write

A 32-bit unsigned integer that specifies the number of elements in
the in_attrs array. This integer must be greater than 0.

space_avail

A 32-bit unsigned integer that specifies the size of the out_attrs
array. This integer must be greater than 0.

in_attrs[]

An array of values of type sec_attr_t that specifies the
attribute instances to be updated. The size of the array is
determined by num_to_write.

Output

num_returned

A pointer to an unsigned 32-bit integer that specifies the number
of attribute instances returned in the out_attrs array.

out_attrs[]

An array of values of type sec_attr_t that specifies the
updated attribute instances. Not that only if these attributes were
processed by an update attribute trigger server will they differ
from the attributes in the in_attrs array. The size of the
array is determined by space_avail and the length by
num_returned.

num_left

A pointer to an unsigned 32-bit integer that supplies the number
of attributes that could not be returned because of space constraints
in the out_attrs buffer. To ensure that all the attributes will
be returned, increase the size of the out_attrs array by
increasing the size of space_avail and num_returned.

failure_index

In the event of an error, failure_index is a pointer to
the element in the in_attrs array that caused the update to
fail. If the failure cannot be attributed to a specific attribute,
the value of failure_index is -1.

status

A pointer to the completion status. On successful completion, the
routine returns error_status_ok. Otherwise, it returns an error.

DESCRIPTION

The sec_rgy_attr_update() routine creates new attribute instances
and updates existing attribute instances attached to a object specified
by name and Registry domain. The instances to be created or updated are
passed as an array of sec_attr_t data types. This is an atomic
operation: if the creation of any attribute in the in_attrs array
fails, all updates are aborted. The attribute causing the update to fail
is identified in failure_index. If the failure cannot be attributed
to a given attribute, failure_index contains -1.

The in_attrs array, which specifies the attributes to be created,
contains values of type sec_attr_t. These values are:

attr_id, a UUID that identifies the attribute type

attr_value, values of sec_attr_value_t that specify the
attribute's encoding type and values.

If an attribute instance already exists which is identical
in both attr_id and attr_value to an attribute
specified in in_attrs, the existing attribute information is
overwritten by the new information. For multi-valued attributes,
every instance with the same attr_id is overwritten with
the supplied values.

If an attribute instance does not exist, it is created.

For multi-valued attributes, because every instance of the
multi-valued attribute is identified by the same UUID, every
instance is overwritten with the supplied value. To change
only one of the values, you must supply the values that should
be unchanged as well as the new value.

To create instances of multi-valued attributes, create individual
sec_attr_t data types to define each multi-valued attribute
instance and then pass all of them in in the input array.

If an input attribute is associated with an update attribute
trigger server, the attribute trigger server is invoked (by the
sec_attr_trig_update() function) and the in_attr
array is supplied as input. The output attributes from the update
attribute trigger server are stored in the registry database and
returned in the out_attrs array. Note that the update
attribute trigger server may modify the values before they are
used to update the registry database. This is the only circumstance
under which the values in the out_attrs array differ from
the values in the in_attrs array.

Permissions Required

The sec_rgy_attr_update() routine requires the update permission
set for each attribute type identified in the in_attrs array.
These permissions are defined as part of the ACL manager set in the
schema entry of each attribute type.