fn_attr_ext_search(3XFN) (man pages section 3: Networking Library Functions)

man pages section 3: Networking Library Functions

fn_attr_ext_search(3XFN)

NAME

fn_attr_ext_search, FN_ext_searchlist_t, fn_ext_searchlist_next, fn_ext_searchlist_destroy– search for names in the specified context(s) whose attributes satisfy the filter

SYNOPSIS

#include <xfn/xfn.h>

ctx

name

control

filter

status

esl

returned_ref

returned_attrs

status

esl

DESCRIPTION

This set of operations is used to list names of objects whose attributes satisfy the filter expression. The references to which these names are bound and specified attributes and their values may also be returned.

control encapsulates the option settings for the search. These options are:

the scope of the search
whether XFN links are followed
a limit on the number of names returned
whether references and specific attributes associated with the named objects that satisfy the filter are returned

The scope of the search is one of:

the object named name relative to the context ctx
the context named name relative to the context ctx
the context named name relative to the context ctx,

and its subcontexts

or
the context named name relative to the context ctx, and a context implementation-defined set of subcontexts

If the value of control is 0, default control option settings are used. The default settings are:

scope is search named context
links are not followed
all names of objects that satisfy the filter are returned
references and attributes are not returned

The FN_search_control_t type is described in FN_search_control_t(3XFN).

The filter expression filter in fn_attr_ext_search() is evaluated against the attributes of the objects bound in the scope of the search. The filter evaluates to either TRUE or FALSE. The names and, optionally, the references and attributes of objects whose attributes satisfy the filter are enumerated. If the value of filter is 0, all names within the search scope are enumerated. The FN_search_filter_t type is described in FN_search_filter_t(3XFN).

The call to fn_attr_ext_search() initiates the search process. It returns a handle to an FN_ext_searchlist_t object that is used to enumerate the names of the objects that satisfy the filter.

The operation fn_ext_searchlist_next() returns the next name in the enumeration identified by esl; it also updates esl to indicate the state of the enumeration. If the reference to which the name is bound was requested, it is returned in returned_ref. Requested attributes associated with the name are returned in returned_attrs; each attribute consists of an attribute identifier, syntax, and value(s). Successive calls to fn_ext_searchlist_next() using esl return successive names and, optionally, their references and attributes, in the enumeration; these calls further update the state of the enumeration.

The names that are returned are composite names, to be resolved relative to the starting context for the search. This starting context is the context named name relative to ctx unless the scope of the search is only the named object. If the scope of the search is only the named object, the terminal atomic name in name is returned.

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

RETURN VALUES

fn_attr_ext_search() returns a pointer to an FN_ext_searchlist_t object if the search is successfully initiated; it returns a NULL pointer if the search cannot be initiated or if no named object with attributes whose values satisfy the filter expression is found.

fn_ext_searchlist_next() returns a pointer to an FN_composite_name_t object (see FN_composite_name_t(3XFN)) that is the next name in the enumeration; it returns a NULL pointer if no more names can be returned. If returned_attrs is a NULL pointer, no attributes are returned; otherwise, returned_attrs contains the attributes associated with the named object, as specified in the control parameter to fn_attr_ext_search(). If returned_ref is a NULL pointer, no reference is returned; otherwise, if control specified the return of the reference of the named object, that reference is returned in returned_ref.

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

ERRORS

If successful, fn_attr_ext_search() returns a pointer to an FN_ext_searchlist_t object and sets status to FN_SUCCESS.

fn_attr_ext_search() returns a NULL pointer when no more names can be returned. status is set in the following way:

FN_SUCCESS: A named object could not be found whose attributes satisfied the filter expression.
FN_E_NOT_A_CONTEXT: The object named for the start of the search was not a context and the search scope was the given context or the given context and its subcontexts.
FN_E_SEARCH_INVALID_FILTER: The filter could not be evaluated TRUE or FALSE, or there was some other problem with the filter.
FN_E_SEARCH_INVALID_OPTION: A supplied search control option could not be supported.
FN_E_SEARCH_INVALID_OP: An operator in the filter expression is not supported or, if the operator is an extended operator, the number of types of arguments supplied does not match the signature of the operation.
FN_E_ATTR_NO_PERMISSION: The caller did not have permission to read one or more of the attributes specified in the filter.
FN_E_INVALID_ATTR_VALUE: A value type in the filter 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(3XFN) and xfn_status_codes(3XFN).

Each successful call to fn_ext_searchlist_next() returns a name and, optionally, its reference in returned_ref and requested attributes in returned_attrs. 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 were 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(3XFN) or fn_attr_multi_get(3XFN) to discover why these attributes could not be returned.

If fn_ext_searchlist_next() returns a name, it can be called again to get the next name in the enumeration.

fn_ext_searchlist_next() returns a NULL pointer if no more names can be returned. status 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 attributes specified in the filter.
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(3XFN) and xfn_status_codes(3XFN).

USAGE

The search performed by fn_attr_ext_search() is not ordered in any way, including the traversal of subcontexts. The names enumerated using fn_ext_searchlist_next() are not ordered in any way. Furthermore, there is no guarantee that any two series of enumerations with the same arguments to fn_attr_ext_search() will return the names in the same order.

XFN links encountered during the resolution of name are followed, regardless of the follow links control setting, and the search starts at the final named object or context.

If control specifies that the search should follow links, XFN link names encountered during the search are followed and the terminal named object is searched. If the terminal named object is bound to a context and the scope of the search includes subcontexts, that context and its subcontexts are also searched. For example, if aname is bound to an XFN link, lname, in a context within the scope of the search, and aname is returned by fn_ext_searchlist_next(), this means that the object identified by lname satisfied the filter expression. aname is returned instead of lname because aname can always be named relative to the starting context for the search.

If control specifies that the search should not follow links, the attributes associated with the names of XFN links are searched. For example, if aname is bound to an XFN link, lname, in a context within the scope of the search, and aname is returned by fn_ext_searchlist_next(), this means that the object identified by aname satisfied the filter expression.

When following XFN links, fn_attr_ext_search() may search contexts outside of scope. In addition, if the link name's terminal atomic name is bound in a context within scope, the operation may return the same object more than once.

XFN does not specify how control affects the following of native naming system links during the search.

EXAMPLES

Example 1 A sample program of displaying how the `fn_attr_ext_search()` operation may be used.

The following code fragment illustrates how the fn_attr_ext_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 search filter 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. See FN_search_filter_t(3XFN) for the description of sfilter and the filter creation operation.

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 search filter to fn_attr_ext_search(). This particular call to fn_attr_ext_search() uses the default search control options (by passing in 0 as the control argument). This means that the search will be performed in the context named by target_name and that no reference or attributes will be returned. In addition, any XFN links encountered will not be followed and all named objects that satisfy the search filter will be returned (that is, no limit). If successful, fn_attr_ext_search() returns esl, a handle for enumerating the results of the search. The results of the search are enumerated using calls to fn_ext_searchlist_next(), which returns the name of the object. (The arguments returned_ref and returned_attrs to fn_ext_searchlist_next() are 0 because the default search control used i fn_attr_ext_search() did not request them to be returned.)

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

/* Declarations */
FN_ctx_t *ctx;
FN_ext_searchlist_t *esl;
FN_composite_name_t *name;
FN_status_t *status = fn_status_create();
FN_composite_name_t *target_name = get_name_from_user_input();
FN_search_filter_t *sfilter = get_search_query();
/* Get context handle to Initial Context */
ctx = fn_ctx_handle_from_initial(status);
/* error checking on 'status' */
/* Initiate search */
if ((esl=fn_attr_ext_search(ctx, target_name,
	/* default controls */ 0, sfilter, status)) == 0) {
	/* report 'status', cleanup, and exit */
}
/* Enumerate names requested */
while (name=fn_ext_searchlist_next(esl, 0, 0, status)) {
	/* do something with 'name' */
	fn_composite_destroy(name);
}
/* check 'status' for reason for end of enumeration */
/* Clean up */
fn_ext_searchlist_destroy(esl);
fn_search_filter_destroy(sfilter);
fn_ctx_handle_destroy(ctx);
fn_composite_name_destroy(target_name);
fn_status_destroy(status);
/*
* Procedure for constructing the filter object for search:
* 	"age" attribute is greater than or equal to 17 AND
*		less than or equal to 25
*	AND the "student" attribute is present.
*/
FN_search_filter_t *
get_search_query()
{
	extern FN_attribute_t *attr_age;
	extern FN_attribute_t *attr_student;
	FN_search_filter_t *sfilter;
	unsigned int filter_status;
	sfilter = fn_search_filter_create(
		&filter_status,
		"(%a >= 17) and (%a <= 25) and %a",
		attr_age, attr_age, attr_student);
	/* error checking on 'filter_status' */
	return (sfilter);
}

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe