man Pages(3): Library Routines

fn_attr_search(3N)

NAME

fn_attr_search, FN_searchlist_t, fn_searchlist_next, fn_searchlist_destroy- search for the atomic name of objects with the specified attributes in a single context

SYNOPSIS

#include <xfn/xfn.h>

ctx

name

match_attrs

return_ref

return_attr_ids

status

sl

returned_ref

returned_attrs

status

sl

DESCRIPTION

This set of operations is used to enumerate names of objects bound in the target context named name relative to the context ctx with attributes whose values match all those specified by match_attrs.

The attributes specified by match_attrs form a conjunctive AND expression against which the attributes of each named object in the target context are evaluated. For multi-valued attributes, the list order of values is ignored and attribute values not specified in match_attrs are ignored. If no value is specified for an attribute in match_attrs, the presence of the attribute is tested. If the value of match_attrs is 0, all names in the target context are enumerated.

If a non-zero value of return_ref is passed to fn_attr_search(), the reference bound to the name is returned in the returned_ref argument to fn_searchlist_next().

Attribute identifiers and values associated with named objects that satisfy match_attrs may be returned by fn_searchlist_next(). The attributes returned are those listed in the return_attr_ids argument to fn_attr_search(). If the value of return_attr_ids is 0, all attributes are returned. If return_attr_ids is an empty FN_attrset_t(3N) object, no attributes are returned. Any attribute values in return_attr_ids are ignored; only the attribute identifiers are relevant for return_attr_ids.

The call to fn_attr_search() initiates the enumeration process. It returns a handle to an FN_searchlist_t object that is used to enumerate the names of the objects whose attributes match the attributes specified by match_attrs.

The operation fn_searchlist_next() returns the next name in the enumeration identified by the sl. The reference of the name is returned in returned_ref if return_ref was set in the call to fn_attr_search(). The attributes specified by return_attr_ids are returned in returned_attrs. fn_searchlist_next() also updates sl to indicate the state of the enumeration. Successive calls to fn_searchlist_next() using sl return successive names, and optionally, references and attributes, in the enumeration; these calls further update the state of the enumeration.

fn_searchlist_destroy() releases resources used during the enumeration. This can be invoked at any time to terminate the enumeration.

fn_attr_search() does not follow XFN links that are bound in the target context.

RETURN VALUES

fn_attr_search() returns a pointer to an FN_searchlist_t object if the enumeration is successfully initiated; it returns a NULL pointer if the enumeration cannot be initiated or if no named object with attributes whose values match those specified in match_attrs is found.

fn_searchlist_next() returns a pointer to an FN_string_t(3N) object; it returns a NULL pointer if no more names can be returned in the enumeration. If returned_ref is a NULL pointer, or if the return_ref parameter to fn_attr_search was 0, no reference is returned; otherwise, returned_ref contains the reference bound to the name. If returned_attrs is a NULL pointer, no attributes are returned; otherwise, returned_attrs contains the attributes associated with the named object, as specified by the return_attr_ids parameter to fn_attr_search().

In the case of a failure, these operations return in the status argument a code indicating the nature of the failure.

ERRORS

fn_attr_search() returns a NULL pointer if the enumeration could not be initiated. The status argument is set in the following way:

FN_SUCCESS: A named object could not be found whose attributes satisfied the implied filter of equality and conjunction.
FN_E_ATTR_NO_PERMISSION: The caller did not have permission to read one or more of the specified attributes.
FN_E_INVALID_ATTR_VALUE: A value type in the specified attributes did not match the syntax of the attribute against which it was being evaluated.

Other status codes are possible as described in FN_status_t(3N) and xfn_status_codes(3N).

Each successful call to fn_searchlist_next() returns a name and, optionally, the reference and requested attributes. status is set in the following way:

FN_SUCCESS: All requested attributes were returned successfully with the name.
FN_E_ATTR_NO_PERMISSION: The caller did not have permission to read one or more of the requested attributes.
FN_E_INVALID_ATTR_IDENTIFIER: A requested attribute identifier was not in a format acceptable to the naming system, or its contents was not valid for the format specified.
FN_E_NO_SUCH_ATTRIBUTE: The named object did not have one of the requested attributes.
FN_E_INSUFFICIENT_RESOURCES: Insufficient resources are available to return all the requested attributes and their values.
FN_E_ATTR_NO_PERMISSION FN_E_INVALID_ATTR_IDENTIFIER FN_E_NO_SUCH_ATTRIBUTE FN_E_INSUFFICIENT_RESOURCES: These indicate that some of the requested attributes may have been returned in returned_attrs but one or more of them could not be returned. Use fn_attr_get(3N) or fn_attr_multi_get(3N) to discover why these attributes could not be returned.

fn_searchlist_next() returns a NULL pointer if no more names can be returned. The status argument is set in the following way:

FN_SUCCESS: The search has completed successfully.
FN_E_PARTIAL_RESULT: The enumeration is not yet complete but cannot be continued.
FN_E_ATTR_NO_PERMISSION: The caller did not have permission to read one or more of the specified attributes.
FN_E_INVALID_ENUM_HANDLE: The supplied enumeration handle was 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).

Other status codes are possible as described in FN_status_t(3N) and xfn_status_codes(3N).

USAGE

The names enumerated using fn_searchlist_next() are not ordered in any way. Furthermore, there is no guarantee that any two series of enumerations on the same context with identical match_attrs will return the names in the same order.

EXAMPLES

Example 1 A sample program of displaying how to use `fn_attr_search()` function.

The following code fragment illustrates how the fn_attr_search() operation may be used. The code consists of three parts: preparing the arguments for the search, performing the search, and cleaning up.

The first part involves getting the name of the context to start the search and constructing the set of attributes that named objects in the context must satisfy. This is done in the declarations part of the code and by the routine get_search_query.

The next part involves doing the search and enumerating the results of the search. This is done by first getting a context handle to the Initial Context, and then passing that handle along with the name of the target context and matching attributes to fn_attr_search(). This particular call to fn_attr_search() is requesting that no reference be returned (by passing in 0 for return_ref), and that all attributes associated with the named object be returned (by passing in 0 as the return_attr_ids argument). If successful, fn_attr_search() returns sl, a handle for enumerating the results of the search. The results of the search are enumerated using calls to fn_searchlist_next(), which returns the name of the object and the attributes associated with the named object in returned_attrs.

The last part of the code involves cleaning up the resources used during the search and enumeration. The call to fn_searchlist_destroy() releases resources reserved for this enumeration. The other calls release the context handle, name, attribute set, and status objects created earlier.

/* Declarations */
FN_ctx_t *ctx;
FN_searchlist_t *sl;
FN_string_t *name;
FN_attrset_t *returned_attrs;
FN_status_t *status = fn_status_create();
FN_composite_name_t *target_name = get_name_from_user_input();
FN_attrset_t *match_attrs = get_search_query();
/* Get context handle to Initial Context */
ctx = fn_ctx_handle_from_initial(status);
/* error checking on 'status' */
/* Initiate search */
if ((sl=fn_attr_search(ctx, target_name, match_attrs,
	/* no reference */ 0, /* return all attrs */ 0, status)) == 0) {
	/* report 'status', cleanup, and exit */
}
/* Enumerate names and attributes requested */
while (name=fn_searchlist_next(sl, 0, &returned_attrs, status)) {
	/* do something with 'name' and 'returned_attrs'*/
	fn_string_destroy(name);
	fn_attrset_destroy(returned_attrs);
}
/* check 'status' for reason for end of enumeration */
/* Clean up */
fn_searchlist_destroy(sl); /* Free resources of 'sl' */
fn_status_destroy(status);
fn_attrset_destroy(match_attrs);
fn_ctx_handle_destroy(ctx);
fn_composite_name_destroy(target_name);
/*
 * Procedure for constructing attribute set containing
 * attributes to be matched:
 * 	"zip_code" attribute value is "02158"
 * 	AND "employed" attribute is present.
*/
FN_attrset_t *
get_search_query()
{
	/* Zip code and employed attribute identifier, syntax */
	extern FN_attribute_t		 *attr_zip_code;
	extern FN_attribute_t		 *attr_employed;
	FN_attribute_t *zip_code = fn_attribute_copy(attr_zip_code);
	FN_attr_value_t zc_value = {5, "02158"};
	FN_attrset_t *match_attrs = fn_attrset_create();
	fn_attribute_add(zip_code, &zc_value, 0);
	fn_attrset_add(match_attrs, zip_code, 0);
	fn_attrset_add(match_attrs, attr_employed, 0);
	return (match_attrs);
}

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe