#include <xfn/xfn.h>FN_search_control_t *fn_search_control_create(unsigned int scope, unsigned int follow_links, unsigned int max_names, unsigned int return_ref, const FN_attrset_t *return_attr_ids, unsigned int *status);
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:
Search just the given named object.
Search just the given context.
Search given context and all its subcontexts.
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:
0 (do not follow links)
0 (return all named objects that match filter)
0 (do not return the reference of the named object)
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.
fn_search_control_create() returns a NULL pointer if the operation fails and sets status as follows:
A supplied search option was invalid or inconsistent.
Other status codes are possible (see xfn_status_codes(3XFN) ).
See attributes(5) for descriptions of the following attributes:
|ATTRIBUTE TYPE||ATTRIBUTE VALUE|