|
The FN_search_control_t object is used to specify options for the attribute search operation fn_attr_ext_search(3XFN).
fn_search_control_create() creates an FN_search_control_t object using information in scope, follow_links, max_names, return_ref, and return_attr_ids to set the search options. If the operation succeeds, fn_search_control_create() returns a pointer to an FN_search_control_t object; otherwise, it returns a NULL pointer.
The scope of the search, scope, is either the named object, the named context, the named context and its subcontexts, or the named context and a context implementation
defined set of subcontexts. The values for scope are:
-
FN_SEARCH_NAMED_OBJECT
- Search just the given named object.
-
FN_SEARCH_ONE_CONTEXT
- Search just the given context.
-
FN_SEARCH_SUBTREE
- Search given context and all its subcontexts.
-
FN_SEARCH_CONSTRAINED_SUBTREE
- Search given context and its subcontexts as constrained by the context-specific policy
in place at the named context.
follow_links further defines the scope and nature of the search. If follow_links is nonzero, the search follows XFN
links. If follow_links is 0, XFN links are not followed. See fn_attr_ext_search(3XFN) for more detail about how XFN links are treated.
max_names specifies the maximum number of names to return in an FN_ext_searchlist_t(3XFN) enumeration (see fn_attr_ext_search(3XFN)).
The names of all objects whose attributes satisfy the filter are returned when max_names is 0.
If return_ref is non-zero, the reference bound to the named object is returned with the object's name by fn_ext_searchlist_next(3XFN) (see fn_attr_ext_search(3XFN)). If return_ref is 0, the reference is not returned.
Attribute identifiers and values associated with named objects that satisfy the filter may be returned by fn_ext_searchlist_next(3XFN). The attributes returned are those listed in return_attr_ids. If the value of return_attr_ids
is 0, all attributes are returned. If return_attr_ids is an empty FN_attrset_t object (see FN_attrset_t(3XFN)), no attributes are returned. Any attribute values in return_attr_ids are ignored;
only the attribute identifiers are relevant for this operation.
fn_attr_ext_search(3XFN) interprets a value of 0 for
the search control argument as a default search control which has the following option settings:
-
scope
-
FN_SEARCH_ONE_CONTEXT
-
follow_links
-
0 (do not follow links)
-
max_names
-
0 (return all named objects that match filter)
-
return_ref
-
0 (do not return the reference of the named object)
-
return_attr_ids
- an empty FN_attrset_t object (do not return any attributes of the named object)
fn_search_control_destroy() releases the storage associated with scontrol.
fn_search_control_copy() returns a copy of the search control scontrol.
fn_search_control_assign() makes a copy of the search control src and assigns it to dst, releasing the old contents of dst. A pointer to the same object as dst is returned.
fn_search_control_scope() returns the scope for the search.
fn_search_control_follow_links() returns non-zero if links are followed; 0 if not.
fn_search_control_max_names() returns the maximum number of names.
fn_search_control_return_ref() returns nonzero if the reference is returned; 0 if not.
fn_search_control_return_attr_ids() returns a pointer to the list of attributes; a NULL pointer indicates that all attributes and values are returned.
|
