man Pages(3): Library Routines

FN_search_filter_t(3N)

NAME

FN_search_filter_t, fn_search_filter_create, fn_search_filter_destroy, fn_search_filter_copy, fn_search_filter_assign, fn_search_filter_expression, fn_search_filter_arguments- filter expression for attribute search

SYNOPSIS

#include <xfn/xfn.h>

status

estr

.

sfilter

dst

src

sfilter

number_of_arguments

DESCRIPTION

The FN_search_filter_t type is an expression that is evaluated against the attributes of named objects bound in the scope of the search operation fn_attr_ext_search(3N). The filter evaluates to TRUE or FALSE. If the filter is empty, it evaluates to TRUE. Names of objects whose attribute values satisfy the filter expression are returned by the search operation.

If the identifier in any subexpression of the filter does not exist as an attribute of an object, then the innermost logical expression containing that identifier is FALSE. A subexpression that is only an attribute tests for the presence of the attribute; the subexpression evaluates to TRUE if the attribute has been defined for the object and FALSE otherwise.

fn_search_filter_create() creates a search filter from the expression string estr and the remaining arguments.

fn_search_filter_destroy() releases the storage associated with the search filter sfilter.

fn_search_filter_copy() returns a copy of the search filter sfilter.

fn_search_filter_assign() makes a copy of the search filter src and assigns it to dst, releasing the old contents of dst. A pointer to the same object as dst is returned.

fn_search_filter_expression() returns the filter expression of sfilter.

fn_search_filter_arguments() returns an array of pointers to arguments supplied to the filter constructor. number_of_arguments is set to the size of this array. The types of the arguments are determined by the substitution tokens in the expression in sfilter.

BNF of Filter Expression

<FilterExpr> ::= [ <Expr> ]
<Expr> ::= <Expr> "or" <Expr>
	       <Expr> "and" <Expr>
	       | "not" <Expr>
	       | "(" <Expr> ")"
       | <Attribute> [ <Rel_Op> <Value> ]
	       | <Ext>
<Rel_Op> ::= "==" | "!=" | "<" | "<=" | ">" | ">=" | "[ap    ]="
<Attribute> ::= "%a"
<Value> ::= <Integer>
	       | "%v"
	       |<Wildcarded_string>
<Wildcarded_string> ::= "*"
	       | <String>
       | {<String> "*"}+ [<String>]
       | {"*" <String>}+ ["*"]
<String> ::= "`" { <Char> } * "`"
	       | "%s"
<Char> ::= <PCS> // See BNF in Section 4.1.2 for PCSdefinition
	       | Characters in the repertoire of a string representation
<Identifier> ::=" "%i"
<Ext> ::= <Ext_Op> "(" [Arg_List] ")"
<Ext_Op> ::= <String> | <Identifier>
<Arg_List> ::= <Arg> | <Arg> "," <Arg_List>
<Arg> ::= <Value> | <Attribute> | <Identifier>

Specification of Filter Expression

The arguments to fn_search_filter_create() are a return status, an expression string, and a list of arguments. The string contains the filter expression with substitution tokens for the attributes, attribute values, strings, and identifiers that are part of the expression. The remaining list of arguments contains the attributes and values in the order of appearance of their corresponding substitution tokens in the expression. The arguments are of types FN_attribute_t*, FN_attrvalue_t*, FN_string_t*, or FN_identifier_t*. Any attribute values in an FN_attribute_t* type of argument are ignored; only the attribute identifier and attribute syntax are relevant. The argument type expected by each substitution token are listed in the following table.

`Token`	`Argument Type`
`%a`	`FN_attribute_t*`
`%v`	`FN_attrvalue_t*`
`%s`	`FN_string_t*`
`%i`	`FN_identifier_t*`

Precedence

The following precedence relations hold in the absence of parentheses, in the order of lowest to highest:

or
and
not
relational operators

These boolean and relational operators are left associative.

Relational Operators

Comparisons and ordering are specific to the syntax and/or rules of the supplied attribute.

Locale (code set, language, or territory) mismatches that occur during string comparisons and ordering operations are resolved in an implementation-dependent way. Relational operations that have ordering semantics may be used for strings of code sets in which ordering is meaningful, but is not of general use in internationalized environments.

An attribute that occurs in the absence of any relational operator tests for the presence of the attribute.

`Operator`	`Meaning`
`==`	The sub-expression is `TRUE` if at least one value of the specified attribute is equal to the supplied value.
`!=`	The sub-expression is `TRUE` if no values of the specified attribute equal the supplied value.
`>=`	The sub-expression is `TRUE` if at least one value of the attribute is greater than or equal to the supplied value.
`>`	The sub-expression is `TRUE` if at least one value of the attribute is greater then the supplied value.
`<=`	The sub-expression is `TRUE` if at least one value of the attribute is less than or equal to the supplied value.
`<`	The sub-expression is `TRUE` if at least one value of the attribute is less than the supplied value.
`[ap ]=`	The sub-expression is `TRUE` if at least one value of the specified attribute matches the supplied value according to some context-specific approximate matching criterion. This criterion must subsume strict equality.

Wildcarded Strings

A wildcarded string consists of a sequence of alternating wildcard specifiers and strings. The sequence can start with either a wildcard specifier or a string, and end with either a wildcard specifier or a string.

The wildcard specifier is denoted by the asterisk character ('*') and means zero or more occurrences of any character.

Wildcarded strings can be used to specify substring matches. The following are examples of wildcarded strings and what they mean:

`Wildcarded String`	`Meaning`
`*`	Any string
`*'ing'`	Any string ending with `ing`
`Any string starting`
`with` `jo`, and containing the substring `ph`,
`and which contains the substring` `ne` in the portion
`of the string following` `ph`, and which ends with `er`
`T}`
`%s*`	Any string starting with the supplied string
`Any string starting with` `bix` and ending with the supplied string
`T}`

String matches involving strings of different locales (code set, language, or territory) are resolved in an implementation-dependent way.

Extended Operations

In addition to the relational operators, extended operators can be specified. All extended operators return either TRUE or FALSE. A filter expression can contain both relational and extended operations.

Extended operators are specified using an identifier (see FN_identifier_t(3N)) or a string. If the operator is specified using a string, the string is used to construct an identifier of format FN_ID_STRING. Identifiers of extended operators and signatures of the corresponding extended operations, as well as their suggested semantics, are registered with X/Open Company Ltd.

The following three extended operations are currently defined:

'name'(<Wildcarded String>): The identifier for this operation is 'name' (FN_ID_STRING). The argument to this operation is a wildcard string. The operation returns TRUE if the name of the object matches the supplied wildcard string.
'reftype'(%i): The identifier for this operation is 'reftype' (FN_ID_STRING). The argument to this operation is an identifier. The operation returns TRUE if the reference type of the object is equal to the supplied identifier.
'addrtype'(%i): The identifier for this operation is 'addrtype' (LM FN_ID_STRING). The argument to the operation is an identifier. The operation returns TRUE if any of the address types in the reference of the object is equal to the supplied identifier.

Support and exact semantics of extended operations are context-specific. If a context does not support an extended operation, or if the filter expression supplies the extended operation with either an incorrect number or type of arguments, the error FN_E_SEARCH_INVALID_OP is returned. (Note: FN_E_OPERATION_NOT_SUPPORTED is returned when fn_attr_ext_search(3N) is not supported.)

The following are examples of filter expressions that contain extended operations:

`Expression`	`Meaning`
`Evaluates to`
`TRUE`
`if the name of the object starts with`
`bill`.
`T}`
`%i(%a, %v)`	Evaluates to result of applying the specified operation to the supplied arguments.
`(%a == %v)` and `'name'('joe'*)`	Evaluates to `TRUE` if the specified attribute has the given value and if the name of the object starts with `joe`.

RETURN VALUES

fn_search_filter_create() returns a pointer to an FN_search_filter_t object if the operation succeeds; otherwise it returns a NULL pointer.

ERRORS

fn_search_filter_create() returns a NULL pointer if the operation fails and sets status in the following way:

FN_E_SEARCH_INVALID_FILTER: The filter expression had a syntax error or some other problem.
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_INVALID_ATTR_IDENTIFIER: The left hand side of an operator expression was not an attribute.
FN_E_INVALID_ATTR_VALUE: The right hand side of an operator expression was not an integer, attribute value, or (wildcarded) string.

Other status codes are possible as described in the reference manual pages for FN_status_t(3N) and xfn_status_codes(3N).

EXAMPLES

Example 1 Creating Different Filters

The following examples illustrate how to create three different filters.

The first example shows how to construct a filter involving substitution tokens and literals in the same filter expression. This example creates a filter for named objects whose color attribute contains a string value of red, blue, or white. The first two values are specified using substitution tokens; the last value, white, is specified as a literal in the expression.

unsigned int status;
extern FN_attribute_t *attr_color;
FN_string_t *red = fn_string_from_str((unsigned char *)"red");
FN_string_t *blue = fn_string_from_str((unsigned char *)"blue");
FN_search_filter_t *sfilter;
sfilter = fn_search_filter_create(
	&status,
	"(%a == %s) or (%a == %s) or (%a == 'white')",
	attr_color, red, attr_color, blue,
	attr_color);

The second example illustrates how to construct a filter involving a wildcarded string. This example creates a filter for searching for named objects whose last_name attribute has a value that begins with the character m.

unsigned int status;
extern FN_attribute_t *attr_last_name;
FN_search_filter_t *sfilter;
sfilter = fn_search_filter_create(
	&status, "%a == 'm'*", attr_last_name);

The third example illustrates how to construct a filter involving extended operations. This example creates a filter for finding all named objects whose name ends with ton.

unsigned int status;
FN_search_filter_t *sfilter;
sfilter= fn_search_filter_create(&status, "'name'(*'ton')");

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe