This set of operations is used to obtain the values of a single attribute, identified by attribute_id, associated with the object named name, resolved in the context ctx. If name is empty, the attribute values associated with ctx are obtained.

The value of follow_link determines what happens when the terminal atomic part of name is bound to an XFN link. If follow_link is non-zero, such a link is followed, and the values of the attribute associated with the final named object are returned; if follow_link is zero, such a link is not followed. Any XFN links encountered before the terminal atomic name are always followed.

The operation fn_attr_get_values() initiates the enumeration process. It returns a handle to an FN_valuelist_t object that can be used to enumerate the values of the specified attribute.

The operation fn_valuelist_next() returns a new FN_attrvalue_t object containing the next value in the attribute and may be called multiple times until all values are retrieved. The syntax of the attribute is returned in attr_syntax.

The operation fn_valuelist_destroy() is used to release the resources used during the enumeration. This may be invoked before the enumeration has completed to terminate the enumeration.

These operations work in a fashion similar to the fn_ctx_list_names() operations.

fn_attr_get_values() returns a pointer to an FN_valuelist_t object if the enumeration process is successfully initiated; it returns a NULL pointer if the process failed.

fn_valuelist_next() returns a NULL pointer if no more attribute values can be returned.

In the case of a failure, these operations set status to indicate the nature of the failure.

Each successful call to fn_valuelist_next() returns an attribute value. status is set to FN_SUCCESS.

When fn_valuelist_next() returns a NULL pointer, it indicates that no more values can be returned. status is set in the following way:

FN_SUCCESS

The enumeration has completed successfully.

FN_E_INVALID_ENUM_HANDLE

The given enumeration handle is not valid. Possible reasons could be that the handle was from another enumeration, or the context being enumerated no longer accepts the handle (due to such events as handle expiration or updates to the context).

FN_E_PARTIAL_RESULT

The enumeration is not yet complete but cannot be continued.

In addition to these status codes, other status codes are also possible in calls to these operations. In such cases, status is set as described in FN_status_t(3XFN) and xfn_status_codes(3XFN).

This interface should be used instead of fn_attr_get() if the combined size of all the values is expected to be too large to be returned by fn_attr_get().

There may be a relationship between the ctx argument supplied to fn_attr_get_values() and the FN_valuelist_t object it returns. For example, some implementations may store the context handle ctx within the FN_valuelist_t object for subsequent fn_valuelist_next() calls. In general, an fn_ctx_handle_destroy(3XFN) should not be invoked on ctx until the enumeration has terminated.

See attributes (5) for descriptions of the following attributes:

FN_attribute_t(3XFN), FN_attrvalue_t(3XFN), FN_composite_name_t(3XFN), FN_ctx_t(3XFN), FN_identifier_t(3XFN), FN_status_t(3XFN), fn_attr_get(3XFN), fn_ctx_handle_destroy(3XFN), fn_ctx_list_names(3XFN), xfn(3XFN), xfn_attributes(3XFN), xfn_status_codes(3XFN), attributes(5)

The implementation of XFN in this Solaris release is based on the X/Open preliminary specification. It is likely that there will be minor changes to these interfaces to reflect changes in the final version of this specification. The next minor release of Solaris will offer binary compatibility for applications developed using the current interfaces. As the interfaces evolve toward standardization, it is possible that future releases of Solaris will require minor source code changes to applications that have been developed against the preliminary specification.