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>

FN_search_control_t * fn_search_control_create(unsignedint scope,

        unsigned int follow_links,
        unsigned int max_names,
        unsigned int return_ref,
        const FN_attrset_t * return_attr_ids,
        unsigned int * status);

void fn_search_control_destroy(FN_search_control_t * scontrol);

FN_search_control_t * fn_search_control_copy(constFN_search_control_t * scontrol);
FN_search_control_t * fn_search_control_assign(FN_search_control_t* dst,
        const FN_search_control_t * src);
unsigned int fn_search_control_scope(const FN_search_control_t * scontrol);
unsigned int fn_search_control_follow_links(const FN_search_control_t * scontrol);
unsigned int fn_search_control_max_names(const FN_search_control_t * scontrol);
unsigned int fn_search_control_return_ref(const FN_search_control_t * scontrol);
const FN_attrset_t * fn_search_control_return_attr_ids(
        const FN_search_control_t * scontrol);

DESCRIPTION

The FN_search_control_t object is used to specify options for the attribute search operation fn_attr_ext_search(3N).

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 contextspecific 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(3N) 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(3N) enumeration (see fn_attr_ext_search(3N)). 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(3N) (see fn_attr_ext_search(3N)). 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(3N). 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(3N)), 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(3N) 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(3N)).

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe

SEE ALSO

FN_attrset_t(3N), fn_attr_ext_search(3N), xfn_status_codes(3N), attributes(5)