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

man pages section 3: Networking Library Functions

fn_search_control_return_ref(3XFN)

NAME

FN_search_control_t, fn_search_control_create, fn_search_control_destroy, fn_search_control_copy, fn_search_control_assign, fn_search_control_scope, fn_search_control_follow_links, fn_search_control_max_names, fn_search_control_return_ref, fn_search_control_return_attr_ids– options for attribute search

SYNOPSIS

#include <xfn/xfn.h>

scope

follow_links

max_names

return_ref

return_attr_ids

status

scontrol

dst

src

scontrol

DESCRIPTION

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.

ERRORS

fn_search_control_create() returns a NULL pointer if the operation fails and sets status as follows:

FN_E_SEARCH_INVALID_OPTION: A supplied search option was invalid or inconsistent.

Other status codes are possible (see xfn_status_codes(3XFN)).

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe