[Go to CFHT Home Page] Man Pages
Back to Software Index  BORDER=0Manpage Top Level
    fn_attr_get_values(3N) manual page Table of Contents

Name

fn_attr_get_values, FN_valuelist_t, fn_valuelist_next, fn_valuelist_destroy - return values of an attribute

Synopsis

cc [ flag ... ] file ... -lxfn [ library ... ] 


#include <xfn/xfn.h>

FN_valuelist_t *fn_attr_get_values(FN_ctx_t *ctx, const FN_composite_name_t *name, const FN_identifier_t *attribute_id, FN_status_t *status);

FN_attrvalue_t *fn_valuelist_next(FN_valuelist_t *vl, FN_identifier_t **attr_syntax, FN_status_t *status);

void fn_valuelist_destroy(FN_valuelist_t *vl, FN_status_t *status);

MT-Level

MT-Safe

Description

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

Return Values

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.

Errors

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(3N) and xfn_status_codes(3N) .

Usage

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() should not be invoked on ctx until the enumeration has terminated.

See Also

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

Notes

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.

Table of Contents